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Chapter 1 Introduction 


1.1 Before You Begin 
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This guide describes how to configure and operate various RDB (Relational Data Base) 
functions in Advant OCS products based on AdvaInform SQL*Connect. 


There are two AdvaInform SQL*Connect options, AdvaInform SQL*Connect and AdvaInform 
SQL*Connect Programming. The AdvaInform SQL*Connect is described in this book. 


AdvaInform SQL*Connect is also called an information server software. It consists of two parts 
- Connect Client and Connect Server. These two parts provide the following functionality: 


° The AdvalInform SQL*Connect Client 


The Connect Client software lets you access object data in the Advant OCS (Open Control 
System) using standard SQL queries. From an operators point of view, it looks as if the 
Advant OCS data were stored in an RDB. 


Example: Assume you are working at a PC on the plant network. The Connect Client lets 
you read data from an Advant OCS object such as an Analog Input (AJ) stored in a Advant 
Controller. You can read the data through a PC based tool (for example, MS-Excel). 


° The AdvalInform SQL*Connect Server 


The Connect Server works in the opposite direction compared to the Connect Client. It lets 
an Advant OCS object access RDB data from Advalnform, or from an external node on 
the plant network. The access is completely transparent in the sense that it is made exactly 
the same way as if the object was stored in a Controller. 


Example: Assume you want some production data stored in an external RDB on the plant 
network to be presented on a process display on an Advant Station 500 Operator Station. 
You then configure the data in your process display exactly the same way as you would 
configure data stored in a Controller. 


The description of the AdvaInform SQL*Connect Client and Server respectively is mainly 
based on a number of use cases. The use cases are presented as a number of tutorials where each 
step is described in detail. In each tutorial, both the required configuration and the following 
operation is described. Besides the tutorials, the configuration and presentation tools (for the 
Client and the Server) are described in detail. 


The guide is intended for those who are responsible for writing SQL applications for the 
Advant OCS. As a prerequisite to using this book, you should already have some system-level 
training or experience with the Advant OCS, and also have some experience with PL/SQL and 
relational databases. 


This guide is not a PL/SQL user’s or reference guide! For detailed information regarding the 
SQL language, refer to Oracles SQL Reference manual(s). 


To learn more about AdvaInform SQL*Connect and other AdvaInform functions, it is 
recommended that you attend the appropriate training courses provided by ABB Industrial 
Systems training centers. 
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1.2 Equipment Requirements 


SQL*Connect is an AdvaInform option designed to run in conjunction with the AdvaInform 
Basic Functions. It runs on all Advant Station 500 Series IMS workstations. 


1.3 How to Use This Book 


If you are an experienced Advant OCS user, you can go straight to the chapter or section dealing 
with the topic you are interested in for the moment. The Table of Contents and the Index helps 
you find where to look. 


If you are an inexperienced user - you do not know very much about Advant OCS or SQL - it is 
recommended that you start by reading all of Chapter 1, Introduction, Chapter 2, Installation 
and Chapter 3, Using the AdvaInform SQL*Connect Client plus the introduction part in Chapter 
4, Using the AdvaInform SQL*Connect Server. The rest of the guide can be seen as reference 
information. 
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1.3.1 Manual Organization 


This book is organized into chapters and sections as shown in Figure 1-1. 
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Section 1.3.1 Manual Organization 
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How to Update 
the Object 
Type Directory 


Figure 1-1. Manual organization 


Chapter 1, Introduction 


This chapter includes basic information about SQL*Connect. 


Chapter 2, Installation 


This chapter tells you how to install SQL*Connect. 
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Chapter 3, Using the Advalnform SQL*Connect Client 


This chapter provides information on how to use the AdvaInform SQL*Connect Client. 


Chapter 4, Using the Advalnform SQL*Connect Server 


This chapter provides information on how to use the AdvaInform SQL*Connect Server. 


Chapter 5, Maintenance & Troubleshooting 


This chapter provides information which you may need in situations when something abnormal 
occurs and when something in the system configuration must be changed 


Chapter 6, FAQ’s and Recommendations 


This chapter includes Frequently asked question and Recommendations. 


1.3.2 Differences Between Systems with Master and MOD 300 Software 


This manual is common for the Advant OCS Systems with MOD 300 respectively Master 
software. This is handled in two ways: 


1.4 Conventions 


1-4 


° In some cases when the operation/commands differs, two alternatives are described - one 
for MOD 300 and one for Master 


° When the difference is restricted to for example object type only, the MOD alternative is 
described in brackets: (MOD: text). 


Most examples, figures and so on are from the Master system. The differences between the 
systems have to be considered when reading the manual. 


Table 1-1 shows the conventions used in this guide: 


Table 1-1. Conventions 


Example 


.. refer to the Advalnform 
SQL*Connect User’s Guide.. 


.. the very first time you .. 


.. press the Return key .. 


.. press the space bar .. 


Type of information 


References to other books are written in /talics. 


Italics used for emphasis. 


The names of keyboard keys are written in Times (same as for 
the rest of the text) and in the same way as on the keyboard 
(initial capital letter for example) in plain text. 


Lowercase letters are used for the name of a key that is not 
labeled on the keyboard. 
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Table 1-1. Conventions (Continued) 


Example 


.. press <Return> .. 


Click or Single Click 
Double Click 
.. SCtrl-C> .. 


.. press the OK button .. 


.. select New from the File 
menu .. 


.. select File - New ... 


.. enter TIC132 into .. 


Type of information 


In tables and procedures, angle brackets replace the word 
“key.” 


Click the left mouse button 
Double click the left mouse button 


A dash is used to indicate that you must simultaneously press 
several keys - Ctrl and C in the example. 


Push and toggle buttons are written the same way as they 
appear on the display. Also, in descriptions, tables and 
procedures, the word “button” is used in conjunction with its 
name. 


Initial capital letters are used for the name of menu items. 


Short for select New from the File menu (above). 


In a tutorial, for example, you may be told to enter a value in a 
field. The value is then written bold faced. 


1.5 Related Documentation 


Table 1-2 lists all documentation related to AdvaInform SQL*Connect. 


Table 1-2. Related Documentation 


Category Title Description 
Station Advant Station 500 Series IMS User’s Guide __| This book provides instructions for system 
administration functions such as backup and 
restore. 
Software Advalnform Basic Functions User’s Guide This book describes the basic functions that 
support all Advalnform software packages. 
Release Notes for SQL*Net & ODBC Part of a delivery. Describes the functionality 
and the installation procedure. 
Advalnform SQL*Connect Programming This book describes the PL/SQL library 
User’s Guide towards Advant OCS objects . 
Other Advalnform Object Types Reference Manual | This book describes the accessible objects in 
the Advant OCS. 
PL/SQL User’s Guide and Reference Oracle referencebook (can be ordered through 
the Advant OCS price list) 
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1.6 Release History 


Table 1-3 lists the major milestones in the development of AdvaInform SQL*Connect. 


Table 1-3. AdvaInform SQL*Connect release history 


Version Description 

1.0 Initial version. 

1.1 Improved functionality and better look and feel. 

1.2 Improved performance. 

2.0 Minor improvements. New Oracle gateway toolkit. 

2.1 SQL*Connect now supports adding of new object types in both Client and 
Server part. New interactive tools for managing the gtw_location table. 
Supports HP-UX 10.20. Licensing for different amount of objects 
introduced. 


1.7 Terminology 


Table 1-4 shows a list of terms associated with AdvaInform SQL*Connect you should be 
familiar with before you go on reading. 


Table 1-4. Terminology 


Term Description 

Advant OCS Advant Open Control System. 

AS 5xx Short for Advant Station 5xx. For example AS 530. 
Attribute Describes the public data of the object (see below). The 


result of an application is most commonly stored in 
attributes. Attributes also contain configured public 
information. Applications (other objects) can request the 
object’s public data through the core system, using 
subscriptions. 


Client A process, such as a Web browser, that interfaces to one or 
more users, sends requests to a server, and presents the 
results of those requests to the users. See also server. 


Advalnform SQL*Connect contains a client and a server 
part. 


Command A command is a request for an action for an object. As a 
result, the object performs the requested action. 
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Table 1-4. Terminology (Continued) 


Term Description 


Core System All nodes in the Advant OCS communicate through the 
Core System. The Core System provides services for 
system applications. Using these services, the system 
applications can communicate, no matter if they reside in 
the same node or in separate nodes of different types. The 
Type Directory (see below) is a part of the Core System, 
and contains information about all object types known to the 


Advant OCS. 
Control network A network that connects different types of Advant Stations 
(Master) and Advant Controllers used to supervise and control a 


specific part of a plant. There can be a maximum of nine 
Control networks. It is possible to exchange data between a 
Control network and the Plant network (see below), and 
also between different Control networks through the Plant 
network. The types of data exchange that are allowed is 
controlled by the set up of the MasterGate filtering 
functions. 


Database Table A Table in the RDB is the place holder for information. 
Tables are organized in rows and columns. A row contains 
information for an RDB instance (for example, an Al in 
Advalnform). A column contains information for a specific 
attribute. 


Database View A Database View in the RDB (see below) context can be 
seen as a “window” or “virtual table” through which you can 
read information from one or more database tables. 


DCS Distributed Control System. 

Display Element A configurable presentation component (or element) that 
represents one or more Advant OCS object. 

ES Short for Advant Station 500 Series Engineering Station. 

External/Internal nodes An external node is a node which is not a member of the 

(computers) Advant OCS concept (internal nodes). An external node 
can access for example an IMS through the X-protocol or 
via SQL*Net. 
Example of an external node: A PC connected to the plant 
network. 

IMS Short for Advant Station 500 Series Information 


Management Station. 
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Term 


Advalnform Basic 
Objects 


IMS menu 


Key 


Object 


Object Directory 
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Table 1-4. Terminology (Continued) 


Description 


Advalnform Basic Objects are instances of pre-defined 

object types used for storage of Advalnform data. They can 

for example be logged by Advalnform History and be used 

in Advalnform applications (user and system). These are 

the available Basic Objects: 

*«  Al,AO: Floating point objects 

. DI,DO: Boolean objects (On/Off) 

¢ TXT: String (text) objects 

. DAT: Objects of type Boolean, Integer, or Floating point 

*  coExecutor: Object used to execute any Advalnform 
program or script 

¢ — coRTM: Object for Run Time Measurement (for motor 
drives normally) 


*  coBasicCalc: Object used to handle various types of 
calculations. Number of inputs to a calculation can be 
in he range 2 to 10. Examples of calculations: sum, 
average. 


The main entry to IMS. That is, the menu that pops up when 
you log in to IMS. 


A unique identifier used in a relational database. Also the 
term Primary key is used. 


In the Advant OCS concept, a combination of data and 

associated procedures (operations) are represented by 

objects. 

Examples of objects are: 

. Process objects. For example PIDCON 

° History logs 

«  Advalnform Basic Objects (Al, AO, DI, DO ... and so 
on, see Advalnform Basic Objects). Refer to the 
Advalnform Object Types Reference Manual for a 
detailed description. 


A place holder for descriptions of object instances (see 
Type Directory below). The Object Directory is a part of the 
Core System (see above). 
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Term 


ODBC 


OS 


Package 


PL/SQL 


Programmer 2000 - 
Pro*C 


RDB 


RDBMS 


Server 


SQL 


SQL*Net 


System Messages 
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Table 1-4. Terminology (Continued) 


Description 


Open DataBase Connectivity. With ODBC installed, 

you can use normal SQL commands to access RDB data. 
ODBC is one of several methods available to get RDB data 
into a PC. 


ODBC supports, for example, Oracle and is normally 
started via an icon on the PC’s Control panel. 


Short for Advant Station 500 Series Operator Station. 


In this context, a group of PL/SQL functions and 
procedures. 


Oracle’s proprietary extension to the SQL language. 
PL/SQL adds procedural and other constructs to SQL that 
make it suitable for writing applications. 


An option that makes it possible to access the relational 
database from a C or C++ application program. 


Relational DataBase. See also Database Table and 
Database View. 


Relational DataBase Management System. A computer 
software program, such as the Oracle RDBMS, that 
manages a relational database. 


A process that executes requests on behalf of another 
process (the client) whose main purpose is to interface the 
user. 


Advalnform SQL*Connect contains a client and a server 
part. 


Structured Query Language. The industry-standard 
language for interfacing to relational databases such as 
Oracle. 


An Oracle software product required to connect an external 
PC to an IMS, thus enabling transfer of RDB data and 
commands in both directions. SQL*Net is available for a 
number of communication protocols. In IMS, SQL*Net for 
TCP/IP is used. 


Advalnform system function which handles and presents 
system messages. 
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Table 1-4. Terminology (Continued) 


Term Description 
TCP/IP Transmission Control Protocol/Internet Protocol. 
Type Directory A table containing descriptions of object types. It is 


important to be aware of that the Type Directory is a part of 
the Core System (see above) whereas the tables and views 
are parts of the RDB. 


1.8 Overview of the Advalnform SQL*Connect Environment 


AdvaInform SQL*Connect consists of one Client part and one Server part, Figure 1-2 refers. 


The Client Part 


The Client part provides SQL read access to objects in the Advant OCS. Write access is also 
possible using the SQL*Connect Programming (which also offers read access on demand, event 
driven or cyclic). The Client part makes the objects in the OCS appear as Oracle relational 
database data. Object instances in the Advant OCS can be queried by name without having to 
know their physical addresses. 


AdvalInform SQL*Connect Client is based on Oracle Open Gateway Technology. If data from a 
database that is not an Oracle RDB is to be accessed, then an gateway towards that specific 
database has to be installed in the IMS or in the external computer. 


The Server Part 


The Server part provides the Advant OCS with cyclic/demand read access to data in external 
databases in the same manner as for process objects. That is, relational database data will appear 
as global objects in the Advant OCS. The external databases must recognize ANSI SQL though. 


SQL*Net provides access to remote Oracle databases. 
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Figure 1-2 gives an overview of AdvaInform SQL*Connect - Client and Server. 
Reports 


Client application/tool with SQL support 


Read access through: 


- SQL 
a 


External relational 
- PL/SQL tig, 1 NEEDS SEINE 
ooao - Pro*C 


SQL 


SQL*Net 
Oracle RDBMS 


LOCATION TABLE 
TABLE_NAME 


Client 


Advalnform SQL*Connect Server | 
NAME SQL*Connect 
Object Name 


Oracle part SQL Server 
TPS fa ool yp_| SQL Server 
V4 ABB Part 
Connect tool 


SQL Client 
tool 
gtwtool 


Symbol name translation 
Demand subscription 


<a 


Cyclic/demand 
data subscription 


Advant OCS system 


Figure 1-2. Advalnform SQL*Connect - Overview 


NOTE 


The SQL Server only supports on demand or cyclic read access. Event 
notification and operations are not supported 


Using Oracle SQL*Net for TCP/IP and creating database links makes it possible to access 
information in remote databases. 
“gateway architecture” to non-Oracle databases. 


The Client side of AdvaInform SQL*Connect is based on Oracle’s SQL*Connect, which is a 


Figure 1-3 shows different access paths where AdvaInform SQL*Connect is involved and also 
where it is not involved. 
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PC Environment External Computer 


Spreadsheet software 


SQL*Net SQL*Net 


Plant Network TCP/IP 


SQL*Net 


Al RDBMS 


Advalnform SQL*Connect 
Client Server 


Display Attributes 


Control Network 


Controller 


OCS Database 


Figure 1-3. Data flow between the OCS system and external systems 


The following is a description of the access paths: 


1 Data flow from a Controller to a PC tool/application. 


Note that there is no intermediate (redundant) storage of data in 
the IMS. Data is fetched from the OCS only when it is requested. 


2 Data from the database in a Controller for presentation on an OS. 


In this case AdvaInform SQL*Connect is not involved. 


3 Data from the Advalnform relational database for presentation on 
an OS. 


4 Data from a remote database for presentation on an OS. 
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In large Master systems with several control networks (Figure 1-4) it is enough to have one 
Advant station, for example IMS, with AdvaInform SQL*Connect. From this station, the 
process data from all controllers in all control networks can be reached, provided that access is 
not prohibited by the MasterGate 230. This is not an issue in MOD 300 systems. 


jt _-SQL*Net for TCP/IP 
= = = = J hmm@ets ws SS ss 
Plant network MB300, TCP/IP 
OS OS IMS 
MB300 Control network 1 
MG 230 L | Controller Controller Controller 


OS OS 
Control network 2 
MG 230 L Controller Controller 
oe Ue Ue zm 
OS OS 
Control network 3 
MG 230 Controller Controller Controller 
Le ee lll = 


Figure 1-4. Access via AdvaInform SQL*Connect in a big configuration. 
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1.9 User Interface 


There are a number of ways to access data through the AdvalInform SQL*Connect Client. Any 
tool using SQL can access Advant OCS data. The following are some methods based on tools 
included in AdvaInform Basic Functions: 


Via an AdvaInform option such as AdvaInform Reports. Consult the applicable user’s 
guide (for example, the Advalnform Reports User’s Guide) for details. 


Interactively - There are two user interfaces included in the AdvaInform Basic Functions 
to access Advant OCS objects interactively: 


— The Database Access window, see Figure 1-5. 


This window is opened via the Database Access menu item in the Station menu. At 
the SQL> prompt, you can enter SQL*Plus queries to access Advant OCS object 
data. Instead of typing in SQL commands, you can execute a script file. 


— The Object Presentation forms, see Figure 1-6. 


This window is opened via the Object Presentation menu item the Station menu. 
As in the Database Access window, you can access Advant OCS object data. 
However, you don’t have to enter SQL queries - just the name of the object. 


SQL*Plus: Release 3.3.2.0.0 - Production on Thu Oct 9 20:32:04 1997 


Copyright (c) Oracle Corporation 1979, 1994. All rights reserved. 


Connected to: 

Oracle? Server Release 7.3.2.3.0 - Production Release 
With the distributed option 

PL/SQL Release 2.3.2.3.0 - Production 


SQL> select name, value from ai where name=’AIC71_1’; 


Figure 1-5. The Database Access window 
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File 


Al Object Presentation 


Help 


AIC71_1 


Section 1 Class -128 


ALARM LIMITS 


MV 


STATUS 


1 Updated 
Man Entry 
Alarm Period Block 
Disturbance 
Signal Error 
Overflow 


£4) Unacknowledge 


PARAMETERS 


Implemented 
Normal Treat 
No Overflow Alarms 


Tested 


Value 27.67 % 


Range Max 100.00 
Range Min .00 


<Insert> 


Figure 1-6. The AI Object Presentation form 


Via the Programmer 2000 - Pro*C option 


You can also use the Programmer 2000 - Pro*C option to write your own C or C++ 


programs to access the relational database. This lets you combine the functionality of the 
AdvaInform User API with the access abilities provided by AdvaInform SQL*Connect, 
and the relational database itself. 


From a performance point of view it is normally best to implement applications using 


Pro*C rather than through scripts using SQL and PL/SQL. 


Typical applications where the Pro*C pre-compiler is recommended are: 


— For reading relational database data from external relational databases (typical 


recipes and product planning information) and use the data to operate your process as 


optimally as possible. 


— For reading information from the Advant OCS (historical information, object 


attributes) and writing that information into an external database. 


The main application can then be started and supervised by the AdvaInform Basic 


Functions software. 
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Chapter 2 Installation 


2.1 General 


The AdvaInform SQL*Connect is included in the Advalnform Basic Software. This means that 
no separate installation is required. 
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3.1 Introduction 


The client part of AdvaInform SQL*Connect provides SQL read access to objects in the 
Advant OCS. The client makes OCS objects appear as if they were data in an Oracle relational 
database. OCS object instances can be queried by name without having to know the physical 
address of the object instances. Thus you can fetch data using standard SQL select statements. 


Figure 3-1 shows the AdvaInform SQL*Connect Client and related OCS components. 


SQL TCP/IP Network 


External computer 


Application/tool ® @ /‘Aavainform SQL*Connect Client > 
Lore database link advantdb > Views Configuration 
connect to my_user identified by DI tool 
my_user using ‘service_name’ ; AO 
create synonym AI for AI@advantdb; a Location Table 
table_name name 
select name, value from AI 


nee NAME = ‘02-POT.1’; wv n + 
SQL/-> CSS translation 27 


Control Network 


Controller Controller 


(Master) 


log 02-POT.1 


Figure 3-1. SQL based application/tool reads data from a Controller. 


How the Client is used to handle different types of data transfer is described in detail in the 
following sections. 
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The following describes what occurs in the example shown in Figure 3-1. The numbers at the 
left correspond to the numbers in Figure 3-1. 


1 In an external computer (for example a PC on the plant network) the following is 
performed: 
° A link to the AdvaInform relational database is created (create database 
link ...) 
° A synonym is created to facilitate entering SQL commands, for example a select 
call(create synonym AI ...). 
° A call for object data is issued (select name, ...). 


To achieve access towards a relational database from a Microsoft standard tool, it is 
common to use ODBC. ODBC supports a number of databases, for example, Oracle. 


2 The select request is received by AdvaInform SQL*Connect Client. 


3 The client transforms the SQL query to a Core System Services (CSS) request used on 
the real-time network. The request is received by a controller on the control network. 


4 The requested data for Analog Input 02—POT.1 is sent back to the PC application 
via AdvalInform SQL*Connect Client. 


Views 


Advant OCS object data are accessed through views. A view can be considered a window or 
virtual table that you can use to read information from one or more database tables. 


There are pre-defined views for the most commonly used Advant OCS object types. If you want 
to add a view to an object type, see Chapter 3.5, Using the AdvaInform SQL*Connect Client. 


NOTE 


A view does not keep a copy of the data. That is, there is no intermediate data 
within AdvaInform SQL*Connect. 


The Location Table 


For object instances to be accessible from AdvaInform SQL*Connect, they must be known by 

the client. To make them known, the object names and the view they belong to are entered into 
the AdvaInform SQL*Connect Location Table (see Figure 3-1). This is generally done via the 

AdvalInform SQL*Connect Client configuration tool. Besides this tool, there are other methods 
for populating and maintain the Location Table. These other methods are described later. 


If you want to access data from other databases, an Oracle gateways towards that specific 
database has to be installed in the Advant Station, or in the external computer. 
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3.2 Tutorial 1 - Reading Data from a Local or Remote Object 


Figure 3-2 shows a simple configuration with an Advalnform client accessing data from a 
controller. 


Advant Station 


( Application | 
SQL 
Issue request 
SQL*Net 
Forward the request to Advalnform Advalnform 
SQL*Connect RDBMS 
Advalnform 
Forward request from Advalnform to Controller SQL*Connect 


Control network ———— 


Controller i Receive request from control network 
Return data 


Figure 3-2. Accessing Controller data via SQL*Net for TCP/IP 


3.2.1 Preparations 


This tutorial shows you how to read data from a Controller object. Before you start, you must 
create a Controller object of type AI. 


3.2.2 Step by step description 


This procedure has two parts: 
° client object instance configuration 


Client object instance configuration refers to adding an object instance to the location 
table. Normally, configuring the Location Table manually, one-object-at-a-time as 
described in this tutorial is not the best approach, see Chapter 3.7, Using the AdvaInform 
SQL*Connect Client. This method is shown here simply to demonstrate the use of the 
AdvaInform SQL*Connect Client configuration tool. 


NOTE 


It should also be noted that the location table is automatically populated with the 
reference to a new object when you execute ordinary select statements towards 
the object. 
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° object access 


Object access refers to the process of entering select statements, execute them and receive 
object data in return. 


Client Object Instance Configuration 
To configure a client object instance in the location table: 


1. Choose SQL*Connect from the AdvaInform menu. This displays a sub-menu, 


Figure 3-3, 
Object Handling 
SQL Connect Client Object Instance Configuration 
History Client Object Type Configuration 
Server Configuration 


IMS 2.0 


ri ialg 
PADDED 


Figure 3-3. Menu item for Configuring the Location Table 


3-4 3BSE 012 638R0001 


3BSE 012 638R0001 


2. 


Aavalnform® SQL *Connect User’s Guide 
Section 3.2.2 Step by step description 


Choose Client Object Instance Configuration from the sub menu. This opens the 
AdvaInform SQL*Connect Client configuration window, Figure 3-4. 


Advalnform SQL Connect Client configuration 


Object Type Name 


Al eee eel 


Object Name 


| Delete | 
Commit Rollback Exit 


Figure 3-4. Advalnform SQL*Connect Client configuration window 


Enter AI as the object type in the Object Type Name field. You can enter AI directly in the 
Object Type Name field, or you can use the list button to display a list of object types, 
Figure 3-5, and then select AI from the list. 


NOTE 


See the Advalnform Object Types Reference Manual for a detailed description of 
object types and their properties. 
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Object Type Name 


Figure 3-5. Object Type names Selection Box 


4. Enter the name of the object instance in the Object Name field, for instance AIC73_2, 
Figure 3-6. 


Object Type Name 


AI 


Object Name 


Figure 3-6. Displaying selected Table Name 


5. Click on Commit to save the entry in the Location Table. 


6. If you want to configure more objects, repeat steps 4 and 5 for each instance. 


Object access 
There are two ways to access the configured AI object: 
° Via the Database Access window 


° Via an Object Presentation form 
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To access the AI object via the Database Access window: 


1. Choose Database Access from the Station menu. This opens the Database Access 
window, Figure 3-7. 


pr rtabase Access SS~w 


SQL*Plus: Release 3.3.2.0.0 - Production on Thu Aug 28 08:11:30 1997 


Copyright (c) Oracle Corporation 1979, 1994. All rights reserved. 


Connected to: 

Oracle? Server Release 7.3.2.3.0 - Production Release 
With the distributed option 

PL/SQL Release 2.3.2.3.0 - Production 


SQL> §j 


Figure 3-7. The Database Access window 


2. Enter SQL command to fetch data. 
At the SQL> prompt, enter following command: 
select name, value from ai where name=’AIC73_2’; 


3. Look at the result, Figure 3-8. 


SQL*Plus: Release 3.3.2.0.0 - Production on Thu Oct 9 20:30:04 1997 
Copyright (c) Oracle Corporation 1979, 1994. All rights reserved. 
Connected to: 


Oracle? Server Release 7.3.2.3.0 - Production Release 
With the distributed option 


PL/SQL Release 2.3.2.3.0 - Production 


SQL> select name, value from ai where name=’AIC73_2’; 


Figure 3-8. Object access via the Database Access window 
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To access the AI object via an Object Presentation form: 


1. Choose Object Presentation from the Station menu, and then choose AI from the sub- 
menu. This opens the AI Object Presentation window, Figure 3-9. See the AdvaInform 
Basic Functions User’s Guide for more information about the presentation. 


Al Object Presentation 


Section 


ALARM LIMITS STATUS PARAMETERS 


MV Updated Implemented 

Man Entry Normal Treat 

Alarm Period Block No Overflow Alarms 
Disturbance Tested 

Signal Error 
Overflow 


Unacknowledge 


Range Max 
Range Min 


<Insert> 


Figure 3-9. The AI Object Presentation Form - empty. 


2. Click on the Query button, then enter the AI object name: AIC73_2, in the text field near 
the top of the window. 
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Al Object Presentation 


AIC73_2 Section 1 


Class 126 


ALARM LIMITS STATUS PARAMETERS 


MY Updated Implemented 

Man Entry Normal Treat 

Alarm Period Block No Overflow Alarms 
Disturbance Tested 

Signal Error 
Overflow 


£) Unacknowledge 


Input Blocked Value 25.00 % Range Max =—-100.00 
Range Min 00 


ee 


<Insert> 


Figure 3-10. The AI Object Presentation Form - with data. 


Click on the Query button again. This fetches the data for AI object AIC73_2 from the 
controller and presents it in the window, Figure 3-10. 
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3.3 Tutorial 2 - How to Read Data from an Advant OCS Object into an 


External PC 


Plant network 


Figure 3-11 shows an application where a PC client accesses data from a controller. 


PC 
RDB Client 


Create a database link to the remote Advalinform Relational database 
Select data from the remote database 


TCP/IP 


SQL*Net 
Receive request from the PC Advalnform 
Forward the request to SQL*Connect RDBMS 
Forward request from Advainform to Controller Advalnform 
SQL*Connect 


Control network 


Advant Station 


Controller 


3.3.1 Preparations 


Receive request from control network 
Return data 


Figure 3-11. Accessing Controller data via SQL*Net TCP/IP 


This tutorial shows you how to get data from an Advant OCS object into a MS-Excel 
application. This includes a summary of how to configure your PC (Section 3.3.1, Preparations). 


3.3.1.1 Advant Station users 


3-10 


How an Advant Station user is defined is different for the IMS and Operator Station. 


On an IMS you log in as a user of category System and start the User Definition dialog via the 
Settings menu in the IMS menu. From there you can define new users. You define a user name, 
valid both in HP-UX, IMS and the Oracle database. Created IMS users will have an Oracle 
account with the same name as the IMS user but with ‘ops$’ added as prefix. For example the 
IMS user testop has a Oracle account ops$testop. In addition, you can add attributes such as: 
User category (IMS user), Oracle database access privileges and so on. To make sure that the 
users of your system have the correct access rights to the Oracle database and the various 
AdvaInform SQL*Connect functions, the system manager has to do this for all AdvaInform 
users. 


On the Operator Station the users are pre-defined. 
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3.3.1.2 History Log 


Create a History log in the Advant Station you want to access. Refer to the Advalnform History 
User’s Guide for detailed information. To get some data into your MS Excel spreadsheet, 
activate the log and let it run for some time. 


3.3.1.3 The PC and the Advant Station 


SQL*Net TCP/IP allows you to run tools and applications in external computers towards the 
Advant OCS relational database. It also enables AdvaInform software to access data in remote 
databases. SQL*Net allows you to connect to multiple databases. 


The basic steps! to configure SQL connectivity from a PC are: 


The PC 


The steps below are examples of some typical steps to configure PC connectivity to Advant 
Stations. There are alternate solutions. For detailed information on how to configure the 
components in your PC, read the applicable installation and configuration guides. 


1. Install and configure TCP/IP. Make the TCP/IP address of your Advant Station known to 
your PC. Verify Advant Station connectivity. 


2. Install SQL*Net for TCP/IP. 


3. Install ODBC (Open DataBase Connectivity) driver for Oracle support, if not already 
installed. 


ODBC is used to access remote ODBC databases and is one of several methods to access 
external data from a PC. ODBC is normally invoked via the Control Panel icon on the PC. 
For detailed information about installation refer to Release Notes for the SQL*Net & 
ODBC option. 


4. Using ODBC supporting Oracle, you define the Advant OCS relational database as a data 
source. You may then pass SQL queries directly to the Advant OCS relational database or 
use remote stored procedures. When you define an ODBC data source the following three 
entries must be defined: 


— Data Source Name - A unique name to identify the data source 
— Server name - connection 


— User Name - The login identity for the data source. The Advant OCS relational 
database can only be accessed by authorized Advant Station users, refer to Section 
3.3.1.1, Advant Station users. 


5. The data source name, as defined above, can then be used by your PC application/tool to 


retrieve data (via SQL commands) from a Controller. 


NOTE 


Consult the appropriate User’s Guide for information on how to make remote 
database access from the application/tool you are using. 


1. For detailed information about installation refer to Release Notes for the SQL*Net & ODBC option 
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6. Verify that you can access the Advant OCS relational database: 
a. Start the application/tool supporting SQL*Net. 


b. Log on to the Advant OCS relational database as an Oracle user relevant for your 
Advant Station, with a connect string according to the syntax described above. 


c. Enter an SQL statement 


For example: SELECT value FROM ai WHERE NAME=’02-POT.1’; 


The AdvaInform SQL*Connect Client will then return data for the object attribute 
value for the AI object instance 02-POT.1. 


The Advant Station 
1. Add an entry in the /etc/hosts file to make the PC known to the Advant Station. 
2. Verify PC connectivity 


Use the command: /usr/sbin/ping PC host name 
from a terminal window 


3. Configure the Location Table (optional). 


The Conitroller 


No configuration required. 
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3.3.2 Step by step description 
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Create an MS Excel spreadsheet on your PC. 


Design the spreadsheet to fit the log data from the Advant OCS relational database that 
you want to access. Assign the spreadsheet aname suchas IMS data to Excel.xls. 
Create columns and assign them names such as Name, Entryvalue, Time, and so on. An 
example is shown in Figure 3-12. 


XX. Micresofé Excel - IMS data to Excel_xls 
all File Edit Yiew Insert Format Tools Data Window 


Help 


ar 


i4[ 4] >| >i Sheet Moduet 7 [4 


Se ns Gs Gs Gs GO RS 


Figure 3-12. Empty MS Excel spreadsheet. 


Write a Visual Basic macro in Excel to fetch data from the Advant OCS database, using 
SQL queries. Then put this data into your spreadsheet. The following is an example of 
such a macro: 


Sub IMS_Excel () 
Application.Run "QueryGetData", 
"DSN=capella; UID=MY_USER; PWD=MY_PWD", "SELECT 


NAME, ENTRYVALUE, TIME FROM numlogval", True, False, False, 
Range ("S$A$2"), True 
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End Sub 


Where: 


DSN is the name of the data source. This is the name of the computer that you get data 


from. You can use the IP address in place of the name. 


UID is the user ID (or user name). When you access data from AdvaInform, the UID must 
be identical to your IMS user name (for example OPS $user). 


PWD is the password for the database user (on IMS the same as the HP-UX user password). 


SELECT is a SQL select statement. NAME, ENTRYVALUE and TIME are the object 
attributes to be read. numlogval is the table name for the numeric log. 


The True and False arguments are optional and can be omitted. If they are omitted, default 
values are used. Their function is to specify how to execute the query and where to put the 
retrieved data. The destination of the data can either be specified with the “Range” 
argument, as in the example macro, or omitted. If omitted, the data will be put into the 
active cell(s) on the spreadsheet. For guidelines on how to use the arguments, refer to the 


Excel on-line help, and search for QueryGetData. 


3. Execute the macro. Figure 3-13 shows the result of an execution of the example macro. 


XX Micresoft Excel - IMS data to Excel. xls 
%}) File Edit View Insert Format Tools Data Window Help -(@ Q 


OEE 7 
$HSLOG22 71_ 
$HSLOG22_71_ 
$HSLOG22 71_ 
$HSLOG22_71_ 
$HSLOG22 71_ 
$SHSLOG22 _ 71_ 
$HSLOG22 71_ 
$HSLOG22_71_ 
$HSLOG22 71_ 
$SHSLOG22 71_ 


[4] >] >if\ Sheett 


14-Apr-97 
14-Apr-97 
14-Apr-97 
14-Apr-97 
14-Apr-97 
14-Apr-97 
14-Apr-97 


Ole|a] Slale| unin le el 


Read: Sum=0 = UL a a i, 


Figure 3-13. MS Excel spreadsheet with result from macro execution. 
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4. Create calculations and/or reports. 


Now you are ready to use the retrieved data in the spreadsheet in calculations and/or 
reports. 


NOTE 


If you have problems when you execute the macro, the ODBC trace log can help 
you debug the macro. You enable the ODBC trace via the ODBC settings icon 
you can find on the Control Panel. 


3.4 The Location Table 


The AdvaInform SQL*Connect Client lets you access Advant OCS objects as if they were 
stored in the relational database. Thus you can query object instances by name without having to 
know the physical addresses of the object instances. 


To make this possible, the objects must be known by the client. This is done automatically for 
most types of queries as long as you specify the name of the object you want to read attributes 
from. Example: SELECT NAME, VALUE FROM AI WHERE NAME=‘TIC100’;. 


For complex select statements where name is not used, it is recommended that you add the 
applicable objects to the location table. This will avoid time-consuming name translations each 
time you issue a request to SQL*Connect for the object. 


You can also use wild cards for the object name or include all objects of a certain type. To be 
able to do this, you must add them to the Location Table. All objects that are defined in the 
location table will be included in the list of objects as a result of in a wild card query. 


Table 3-1 provides some example entries in the Location Table: 


Table 3-1. AdvalInform SQL*Connect Location Table 


Object Name Object Type") 
FC335 CCF_PID_LOOP / PIDCON 
FFY54 CCF_CNTRL_LOOP / MANSTN 
FAN101 CCF_DEVICE_LOOP / RATIOSTN 
$HSTC200,MEASURE-1-o NUMLOGVAL 


(1) Shows MOD 300/Master object types respectively. 


The first time you query an object instance listed in the Location Table, the Core System locates 
the instance and resolves its physical address. Subsequent queries execute faster because they 
use the resolved address. Figure 3-14 shows what happens in the external computer, the Advant 
Station and the Controller when you enter a SQL query. 
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Core System Core System Oracle Oracle 
Physical Resolved F Client 
Objects —e( Location Tab. maven 
Control| Network SQL*Net 
Controller Advant Station External 
computer 


Figure 3-14. Example of data flow through Advalnform SQL*Connect Client 


How to enter object instances into the Location Table is described in Section 3.4.1, How to 
Configure the Location Table. 


NOTE 


The Location Table is intended for internal AdvaInform SQL*Connect use only. 
Do not use it in any of your applications. ABB Industrial Systems does not 
guarantee that it will exist, or have the same design, in future versions of 
AdvaInform SQL*Connect. 


3.4.1 How to Configure the Location Table 
There are mainly four tools/methods you can use to configure the Location Table: 


° The AdvaInform SQL*Connect Client tool which is invoked via the SQL* Connect menu 
item in the AdvaInform menu. 


° SQL SELECT calls that can be entered in the Database Access window. 


° Scripts. One script is then used to configure a number of objects. The script uses a 
SELECT call for each object to be configured. 


° A gtw utility. Refer to Section 3.4.1.4, Scanning and Populating Utilities. 


The first and second methods ARE NOT recommended if you want to configure a large number 
of objects. In that case you should use method three or four. All four methods are described in 
greater detail in the following sections. 


3.4.1.1 Client Object Instance Configuration Tool 


How to Add an object to the Location Table 
To add an object to the Location Table using the AdvaInform SQL*Connect Client tool: 


1. Choose SQL*Connect from the AdvaInform Menu. This displays a sub-menu, 
Figure 3-15. 
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DZ. 


Choose Client Object Instance Configuration from the sub menu. 


Object Handling 

SQL Connect Client Object Instance Configuration] 

History Client Object Type Configuration 
Server Configuration 


File Station AdvaBuild Advalnform AdvaTalk Session Settings Help 


IMS 2.0 


ri ialg 
PADDED 


Figure 3-15. Menu Item for Configuring the Location Table 


This opens the AdvaInform SQL*Connect Client Object Instance configuration window, 
Figure 3-16 


Advalnform SQL Connect Client configuration ° 


Object Type Name 


eee (5) 


Object Name 


l Count: *0 <Insert> 
ae 


Figure 3-16. Client Object Instance configuration window 
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Enter an object type name in the Object Type Name field. 


If you know the object type name (for example: AI), you can enter the object type name 
directly in the field. 


If you do not know the object type name, you can select it from a list of object type names. 
To display this selection box, click on the list button next to the Object Type Name field. 


This displays the Object Type Name selection box, Figure 3-17. 


Figure 3-17. Object Type names Selection Box 


Use the scroll bar to traverse through the text in the viewing area. Double click on the table 
name, or use OK to select the table name you want. This returns you to the AdvaInform 
SQL*Connect Client window with the selected object type, Figure 3-18. 


NOTE 


You can click on Cancel to exit the selection box without making a selection 


Advalnform SQL Connect Client configuration 


Object Type Name 


Al 


Object Name 


fi [AIC3 2. 
rc. — as 


Figure 3-18. Selected Table Name Displayed in Connect Client Window 


Enter the name of the object instance in the Object Name field. 
Press Commit to save the entry in the Location Table. 
Repeat steps 4 and 5 for each object instance you want to add to the Location Table. 


See Advalnform Object Types Reference Manual for a detailed description of object types 
and their names. 
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3.4.1.2 Select calls 


3.4.1.3 Script Files 
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How to Delete an object in the Location Table 

You can also delete an object instance from the Location Table: 

1. Select Object Type (type in or select from the Object Type Name list) 
Select the object instance you want to delete 


Click on Delete. 


= oS 


Press Commit to delete the entry in the Location table. 


The Location Table can also be configured indirectly by executing SELECT statements. The 
Location Table is updated when you use a SELECT statement that explicitly specifies an object 
by its name. For Example: 


SELECT name,value,hi_liml FROM AI WHERE name=’TC500’; 


When such a query is executed, the core system checks if an object instance with a matching 
name exists in any of the known nodes. If the object (for example TC500) is not in the 
Location Table, and the core system can resolve the object name, the Client will add it to the 
Location Table. The data is returned and subsequent queries for the object instance will use the 
resolved address. 


This method works only if the “where” clause contains the object instance name. The Location 
Table is not updated when the name is specified with a wildcard (for example, PRES%), or when 
the instances are specified indirectly (for example, where value > 25), even though these 
are valid queries. 


NOTE 


If you want to add instances to the table for one of the CCF object types, be sure 
to use the NAME attribute and NOT THE TAG attribute to identify the instance. 


Queries that update the Location Table can come from any valid source such as AdvaInform 
Reports or the Database Access window. In addition, when you make a request for information 
about a specific object instance using any of the Object Forms windows, a query of this type 
(SELECT) is issued. 


If you are going to configure hundreds or thousands of objects, the methods described in Section 
3.4.1.1, Client Object Instance Configuration Tool and Section 3.4.1.2, Select calls are NOT 
recommended. 


The recommended way to populate the Location Table with a large number of objects is to use 
script files or a population utility (see Section 3.4.1.4, Scanning and Populating Utilities). 


The script file is a text file with one SQL SELECT statement per object to be configured. When 
the script file is created, it can be run by entering just a single command. If the Location Table 
data for some reason is lost, you just run the script file again. 
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The following is an excerpt from a script file: 


SELECT NAME 


ROM AI 


HERE NAME=’AI object 1’; 


ROM AI 


F 
W 
SELECT NAME 
EF 
W 


HERE NAME=’AI object 2'; 


Seed ile and so on ..... 


“AI object x” represents a specific name of an AI object. When you run the script above, 
each of the SELECT statements will be executed in the order they occur in the file. This is 
equivalent to executing the statements one-at-a-time as described in Section 3.4.1.2, Select 
calls. 


For information on utilities and methods to create and work with script files for population of 
the Location Table, refer to Section 3.4.1.4, Scanning and Populating Utilities. 


These queries will return data and are therefor more suited for object access. Access towards 
history logs may retrieve much data and there for the next method is recommitted for history 
population. 


3.4.1.4 Scanning and Populating Utilities 
Four utilities are provided for managing the AdvaInform SQL*Connect Location Table: 
° gtuCheckLT - Finds objects that no longer respond/exist 
° gtuPopLT - Populates objects automatically into the Location Table 
° gtuListLogs - Creates a list of active History logs 
° gtuListAll - Lists all objects in the Location Table 


All utilities are available under /opt/advant/Connect/bin. 


gtuCheckLT 


Use gtuCheckLT to find out which objects that no longer exist in Advant OCS but still are in the 
Location Table. This utility presents a list of those objects, and prompts you to choose whether 
or not to delete them. The dialog lets you delete them one-by-one, or all in one action. Objects 

in nodes that are down are not presented as candidates for deletion. 


Syntax gtuCheckLT <time-out> <-log> 


time-out Optional parameter. Time to wait for each set of 100 objects to be checked. 
Default is 5 seconds, minimum is 1 second and maximum is 30 seconds. 


-log Optional parameter. If specified, the number of checked objects will be echoed 
on the screen for every 100 objects. 
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Example: 


S$ gtuCheckLT -log 


Checking objects of type AI 


100 objects checked 
148 objects checked 


122 unresolved objects found 


Delete AIC71_122? (y/n/all/quit) 
Delete AIC71_123? (y/n/all/quit) 
Delete AIC71_124? (y/n/all/quit) 
Delete AIC71_125? (y/n/all/quit) 


yly 
yly 
yly 
yla 


pall eal apall apa 


Are you sure? (y/n) y 
Checking objects of type AO 


100 objects checked 
177 objects checked 


174 unresolved objects found 

Delete AOC71_101? (y/n/all/quit) [y] a 
Are you sure? (y/n) y 

Checking objects of type DI 


100 objects checked 
200 objects checked 
220 objects checked 


220 unresolved objects found 


Delete DIC71_1? (y/n/all/quit) [y] a 


Are you sure? (y/n) y 
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gtuPopLT 


Use gtuPopLT to add objects to the Location Table. Object names are read from a text file, one 
line for each name. Only objects that can be resolved will be inserted into the Location Table. 
Objects that can not be resolved will be echoed to the screen. 


Syntax gtuPopLT file name <time-out> <-log> 
or 


gtuPopLT file name -history <-log> 


file name Name of file to read object names from. This file must have one line for each 
name. 


time-out Optional parameter. Time to wait for each set of 100 objects to be resolved. 
Default is 600 seconds, minimum is 10 second and maximum is 10000 
seconds 


-history — Use this flag if the input file only contains names of History logs. 


-log Optional parameter. Display the number of handled objects on the screen for 
every 100 objects. 


Example: 

S$ gtuPopLT names.txt 1200 -log 
Number of handled objects: 100 

Number of handled objects: 200 

Number of handled objects: 224 


gtuListLogs 


Use gtuListLogs to print the names of all active History logs on a text file, one name per line. 


NOTE 
You can use the output from gtuListLogs as input to gtuPopLT. 


Syntax gtuListLogs file name <-active/-all/-accessnames> 
file name Name of file where to print the names of all active logs. 
-active Optional parameter. If set, all active logs will be printed on the text file. 


This is default. 


-all Optional parameter. If set, all logs will be printed on the text file - active 
and not active. 


-accessnames Optional parameter. If set, the accessnames instead of the regular names 
will be printed on the text file. 
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Examples: 

S$ gtuListLogs HistoryLogs.txt 
The names of all active logs will be printed to file HistoryLogs.txt 
S$ gtuListLogs HistoryLogs.txt -all 


The names of all active and not active logs will be printed to file HistoryLogs.txt. 


S$ gtuListLogs HistoryLogs.txt -accessnames 


The access names of all active logs will be printed to file HistoryLogs.txt. 


gtuListAll 


Use gtuListAll to print the names of all objects in the Location Table to a specified text file. 


Syntax gtuListAll file name <-types> 

file name Name of file where to print the names of all objects. 

-types Optional parameter. If set, then also the object type names will be printed. 
Example: 


S$ gtuListAll Objects.txt -types 


All object instance names and types will be printed on file Objects. txt. 
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3.5 The Client Object Type Configuration Tool 
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The AdvaInform SQL*Connect Client supports a number of standard object types. You can 
extend the supported types by installing other object types available in the Type Directory. You 
must be, at least, of category Engineer to perform this procedure. 


To add or remove an object type: 


Choose SQL Connect from the AdvaInform menu, and then choose Client Object Type 
Configuration from the submenu. This displays the dialog box in Figure 3-19 


File Help 


Available Object Types 
ACNODE BLO 


AEHAWKRIDGEINTERFA BOTIMEROBJECT 


OMFAPPLICATION 
OMFAPPSHELL 


Messages 


Figure 3-19. The SQL*Connect Client Object Type Configuration dialog box 
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The following information is displayed (see Figure 3-19). 


Lists 


Installed Object Types 


Available Object Types 


Messages 


Buttons and Text fields 


<<Add 


Remove>> 


Filter 


Displays all object types that are accessible via the AdvaInform 
SQL*Connect Client. 


Displays the object types in the type directory that can be added 
to the Installed Object Types list. 


Presents information and error messages depending on what 
operation has been performed. 


If there is an error when an object type is installed, an error 
message is displayed in the Messages list. Any object type that 
could not be installed will be automatically returned to the 
Available Object types list. 


Used to move an object type from the Available Object Types 
list to the Installed Object Types list. First select an object type 
in the Available Object Types list, then click on the <<Add 
button. The object type is added to the Installed Object Types 
list. 


Used to move an object type from the Installed Object Types 
list to the Available Object Types list. First, in the Installed 
Object Types list, click on the object type you want to remove. 
Then click on the Remove >> button. The object type is added 
to the Available Object Types list. After removal of an object 
type, the Client will not be able to access that object type. 


There are two text fields named Filter, one for the Installed 
Object Types list, and one for the Available Object Types list. 


The Filter fields can be used to reduce the number of displayed 
objects in the respective fields. This is done by entering a text 
pattern in any of the text fields. 


Filtering is done by matching the string value in the edit field 
with the values in the list. There are two ‘wild-card’ characters 
defined, ‘%’ matches any number of characters and ‘_’ matches 
any single character. 


The default value in the text fields is a single ‘%’ character, this 
matches all object type names. 


Changes made in a filter edit field becomes active when the 
TAB or the Return key is pressed, or when there is a mouse 
click on another button, for example << Add. The TAB key 
moves focus to the next button. 
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The File menu 


Row count 


Revert 


Save 


Exit 


When you use the AdvaInform SQL*Connect Client for query 
such as- SELECT * FROM AT; - the result may contain a very 
large number of rows. This in turn can generate a heavy load on 
the Advant OCS. To prevent users from causing a high load this 
way, the AdvaInform SQL*Connect Client does not allow 
statements to return more than a pre-defined number of rows. 


The recommended way of writing a select statement is to include 
the object name, for example: 


SELECT * FROM AI WHERE NAME=’AIC71_1’; 


If you have an application where the number of rows returned 
must be more, or less, than 50 (the default value) and you can not 
specify the object names, you can alter the row count limit. This 
modification is done per object type using the Change Row 
count dialog, Figure 3-20. To display this dialog, choose Row 
count from the File menu. 


Choose Revert to revert changes made since the last save. 


The real installation of a object type into SQL*Connect Client is 
made when the Save menu alternative is invoked. 


Exit the Client Object Type Configuration tool. 
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3.5.1 Change Rowcount display 


: “Change Rowcount 


f) Show object types with default rowcount 


f) Show object types with altered rowcount 


Rowcount 


Default 
Default 
500 

250 

Default 
Default 
Default 
Default 
Default 


ee | 


Figure 3-20. Change Row count dialog box 


Lists 


Type / Row count List of object types for which you can change the row count 
value. The current row count for the type is displayed in the Row 
count column. If the row count has not been changed for an object 
type, the current row count is indicated as Default. 

To select a type click on its name in the Type column. To select 
more than one type, drag the mouse over the list, or press the 
Control key while you click in the list. 
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Buttons and text fields 


Type 


Show object types with 
default row count 


Show object types with 
altered row count 


Row count 


Apply 
Default 


Exit 


Help 


3.6 Restrictions 


Used to filter the object types displayed in the list. Default is 
presentation of all object types installed in the AdvaInform 
SQL*Connect Client. 


Filtering on object type name is done by matching the string value 
in the Type text box with the values in the list. There are two 
“wild-card” characters defined: 

- “%’ - matches any number of characters 

Example: “A%” will show all object types with an “A” as the first 
character, for example: AO. 

- “_” - matches any single character. 


Example: “A_” will show all object types starting with an “A” 
and having a length of two characters, for example: AI. 


If you click on this button only the object types having the default 
row count will be displayed. 


If you click on this button only the object types not having the 
default row count will be displayed. 


The value entered into the Row count field can be any positive 
number greater than zero. 


If one object type is selected, then its row count value is displayed 
in the Row count text box. 


If several object types having the same row count are selected, 
then that row count value is displayed. If the object types have 
different row count values, nothing is displayed. 


Apply activates the value you entered in the Row count field. 


Used to revert the row count to its default value. First, select one 
or more object types, then click on the Default button 


Exit the Change Row count dialog box. 


To get help on how to use the dialog box. 


You can install all object types defined in the type directory, that have defined attributes, 
including the types created by AdvaBuild Object Type Builder. Some object types have 
complex attributes, for example bit sets and open arrays, which are not supported by the 
AdvaInform SQL*Connect Client. These attributes are omitted from the table that is created 
when the object type is installed in the AdvaInform SQL*Connect Client. Most of the types 
available from the type directory are of little use to the end user; however, they are included in 
the lists in case there is a need to install them. In general only the object types described in the 
Advalnform Object Types Reference Manual should be installed. 
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Object types predefined by ABB can not be removed from the AdvaInform SQL*Connect 
Client. However, you can alter the row count for these predefined object types. 


Object types that do not exist in the type directory can be installed in the AdvaInform 
SQL*Connect Client. This can occur when a user-created object type, that is installed in the 
AdvaInform SQL*Connect Client, is removed from the type directory. Also, there are some 
special object types created by ABB that do not reside in the type directory, for example 
NUMLOGVAL. You can alter row count for and remove these types. 


The Oracle relational database restricts the length of column names in tables to 30 characters. In 
some cases the names of attributes in an object type are longer than 30 characters. This is solved 
by shortening the name and adding two unique characters to the end of the name. The original 
column name is stored in a table that can be reached via the GTW_COL_COMMENTS view. 


The following example displays column names and corresponding comments for the AI object 
type: 


SELECT COLUMN_NAME, COMMENTS, FROM GTW_COL_COMMENTS WHERE 
TABLE _NAME=’ AI’; 


3.7 SQL Queries - Examples and Recommendations 
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AdvaInform SQL*Connect supports the following SQL statements: 


° SELECT statement including all its clauses (INTO, FROM, WHERE, GROUP BY, 
HAVING, and ORDER BY) 


° COMMIT statement 


NOTE 


When writing SQL scripts, as part of AdvaInform applications, which include 
invocation of SQL*Plus from the UNIX command line prompt, AdvaInform 
object names which include the ‘$’ character are treated as substitution variables 
instead of ordinary characters, when used as part of an SQL statement in the 
script. Typing an escape character (‘\’) before the ‘$’ character in object names 
will force SQL*Plus to treat the ‘$’ as an ordinary character. 


SQL queries towards objects are similar in format to regular SQL queries towards relational 
database tables. Table 3-2 shows how to interpret the normal SQL table, row and column 
concepts when accessing an object (for example, AdvaInform Basic Objects or Process Object). 


Table 3-2. RDBMS vs. Object terminology 


Oracle data Object Concept 
Table or view Object Type 
Row Object Instance 
Column Attribute 
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Below are two examples of an AdvaInform SQL*Connect query, one for Master and a 
corresponding one for MOD 300: 


Master 


MOD 300 


SELECT value 
FROM PIDCON 
WHERE value > 500 
ORDER BY value; 


SELECT tag, measure, setpoint, engunits 
FROM ccf_pid_loop 

WHERE measure > 500 

ORDER BY measure; 


Parts of the SELECT statement are described below: 


The SELECT part specifies the object attributes to retrieve. 


Object attributes can be manipulated mathematically, for instance: 


SELECT measure + 10 FROM 


This retrieves a value equal to the measured value plus 10. 


A complete listing of process object attributes is provided in the Advalnform Object Types 
Reference Manual. 


The FROM clause specifies the name of an Advant OCS object type. 


Object type names are provided in the Advalnform Object Types Reference Manual. You 
can also list the available object types with the AdvaInform SQL*Connect Client 
configuration tool. 


The WHERE clause can be used to specify conditions for the query. 


In the MOD 300 and Master examples above, the condition specifies that only objects with 
a measured value greater than 500 will be retrieved. 


The ORDER BY clause determines the order that instances are returned in. 


Instances are returned in ascending order by default. You can specify that instances be 
returned in descending order by entering DESC after the attribute. For instance: 


ORDER BY measure DESC 


For details about SQL syntax, refer to the Oracle SQL Reference Manuals. 
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Recommended Query Format 


The most efficient method for queries is to explicitly include the name of the object instance. 
For example: 


Master 


SELECT name, value, description FROM AI 
WHERE NAME=’ATC15_1’; 


MOD 300 


SELECT name, result FROM data_fcm WHERE name=’ LP-MISC1.DAT’; 


This method is fast and secure since it limits the load on the Control Network and the 
Controllers. If the object instance is listed in the Location Table, the client is able to directly 
retrieve data for it. If the object instance is not in the Location Table, the Core System resolves 
the instance, retrieves the data, and puts the instance into the Location Table so that it can be 
processed more quickly at the next query. 


NAME VALUE DESCRIPTION 


AIC15_1 4.000 Calculated pressure 


Figure 3-21. Example of result from an SQL query. 


Other Query Formats 


SELECT statements which do not explicitly state the object instance names put more demands 
on system resources. Examples of such statements are: 


Master 


SELECT name, value, hi_liml FROM AI; 


SELECT name, value, hi_liml FROM AI WHERE value>hi_liml; 


SELECT name, value, hi_liml FROM AI WHERE NAME LIKE 'AIC3’; 


SELECT name, result FROM data_fcm; 


These statements cause the Core System to try to resolve and fetch data from all object instances 
of type AI in the Location Table. 


If the Location Table contains more names than granted, and the SELECT statement does not 
explicitly state the object instance name (WHERE NAME =), the query is not allowed. It will 
result in two error codes: “ORA-01031: insufficient privileges” and “ORA-02063: preceding 
line from GTW”. The default granted row count is 50; however, this value can be changed, see 
Section 3.5, The Client Object Type Configuration Tool. 


If the system load is high or if many nodes must be checked before the physical address can be 
resolved, the request might time out. In such a case, a request, issued as a SELECT statement, 
results in a message: “No rows selected”. 
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NOTE 


Time-out can also result in a subset of the object instances included in a query not 
returning the requested data. 


A communication problem with a node can affect the query results. If there is a communication 
problem with the node that contains the object instance, a query which explicitly names the 
object instance returns no data. For example, the following queries return no information if 
there is a communication failure with the node that contains the TC600 object: 


Master 


SELECT name, value FROM PIDCON WHERE name = ‘TC600’; 


MOD 300 


SELECT name, measure FROM ccf_pid_fcm WHERE name = 
*TC600’; 


3.7.1 Guidelines for Reading Objects via Advalnform SQL*Connect 
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This section presents general guidelines for reading various object types. Table 3-3 provides the 
names of SQL views tables for Advant OCS data, and describes the kind of data contained in 
the table. 


The tables that contain CCF data are based on CCF object types. The Advalnform Object Type 
Reference Manual contains complete listings of these tables. 


Table 3-3. Example of Object Types in Advalnform SQL*Connect 


MOD 300 or Master /Table/View Purpose 
NUMLOGVAL Historical values from numeric historical logs 
HS_MSG Messages from all historical message logs. To get a more 
Common concise view of EAMSGLOG, use BCHS_ MESSAGES as 
described below. 
ENCAP_DATA Used by AdvaInform Reports users to put data from an 
executed report into a new report 


3BSE 012 638R0001 


Aavalnform® SQL *Connect User’s Guide 
Section 3.7.1 Guidelines for Reading Objects via Advalnform SQL *Connect 


Table 3-3. Example of Object Types in Advalnform SQL*Connect (Continued) 


MOD 300 or Master /Table/View Purpose 
CCF_CONTIN_LOOP Loop values from continuous loops which have no 
Auto/Manual or PID Controller FCMs 
CCF_CNTRL_LOOP Loop and Auto Manual Controller FCM attributes from 
continuous loops which have Auto/Manual FCMs. 
CCF_PID_LOOP Loop and PID FCM attributes from continuous loops which 
MOD 300 have PID FCMs but do not use adaptive reset or adaptive gain. 
CCF_1ADAPT_LOOP Loop and PID FCM attributes from continuous loops which 
have PID FCMs and use either adaptive reset or adaptive gain. 
CCF_2ADAPT_LOOP Loop and PID FCM attributes from continuous loops which 
have PID FCMs and use both adaptive reset and adaptive gain 
FCM object types Each FCM type has an object type associated with it. 
CCF_DEVICE_LOOP Device loop attributes 
Master AI, AO, DI, DO, TXT, DAT | Reading attributes from Advant OCS objects from either the 


local or remote nodes. 
Al is used to read AI objects, AO for AO objects, and so on. 


3.7.1.1 Guidelines for MOD 300 CCF Object Types 


Use the CCF_CONTIN_LOOP object type for the basic continuous CCF loops that have no 
controller FCMs. There are no FCM attributes in this object type. If you wish to read the value 
of a Math FCM attribute from one of these loops, use the math_fcm object type. 


To read information for a loop that has an Auto/Manual FCM use the CCF_CNTRL_LOOP 
object type. This object type contains both loop-level attributes and auto/manual controller 
FCM attributes. However, attributes of the other FCMs of the loop are not in this object type. 
For example, if you want to read a value from the Analog Input FCM of the loop, you read it 
from the FCM_ AINP object type. 


Values for PID Controller loops are provided in one of the following object types, depending on 
the kind of loop: CCF_PID_LOOP, CCF_!ADAPT_LOOP, and CCF_2ADAPT_LOOP. Use 
CCF_PID_LOOP when the loop DOES NOT have any adaptive functions. Use the ADAPT 
object types only when the PID loop uses an adaptive function. If the loop uses one kind of 
adaptive function (either adaptive gain or adaptive reset), use CCF_1ADAPT_LOOP. If the loop 
uses both adaptive gain and reset, use CCF_2ZADAPT_LOOP. 


The PID Controller loop object types contain both loop-level attributes and PID controller 
attributes. However, attributes of the other FCMs that may be included in the loops are not in 
these object types. For example, if you want to read a value from the Analog Input FCM of the 
loop, you read it from the FCM_ AINP object type. 
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When you configure the location table, it is best to associate a PID loop with the proper object 
type. However, if you associate a loop with an incorrect type, you may be able to read a subset 
of the loop’s data. For example if you associate a PID controller loop with object type 
CCF_CONTIN_LOOP, you can read the loop level attributes such as Measure and Alarm State, 
but you cannot read the PID attributes such as Base Gain. 


Each FCM type has an associated FCM Object Type which can be used to read information 
from those FCMs. For example, if you want to read the result of the Analog Output FCM of 
loop TCS50, a possible query is: 


SELECT name, result FROM fcm_aout WHERE name = ‘TC50.AOT’; 


Note that the name attribute for an FCM is in the standard CCF format, i.e., tag.femname. 


Use CCF_DEVICE_LOOP to read device loop attributes. 


Tag and Name Attributes 


AdvaInform SQL*Connect can read the tag from either the name attribute or the tag attribute. 
For example, the following queries retrieve the same data: 


SELECT tag, measure FROM ccf_pid_loop WHERE tag = ‘LC200’; 
SELECT name, measure FROM ccf_pid_loop WHERE name = ‘*LC200’; 
SELECT tag, measure FROM ccf_pid_loop WHERE name = ‘LC200’; 


However, there is an important difference between the two attributes. The Location Table 
identifies object instances by the name attribute. Therefore, the following query can be used to 
put an entry for LC200 in the location table: 


SELECT name FROM ccf_pid_loop WHERE name = ‘LC200’; 


In contrast, a query that identifies a loop by its tag attribute does not update the location table. 


3.7.1.2 Recommendations for Reading Basic and User Objects (IMS specific) 
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Local Basic and User Objects within IMS can be read using either AdvaInform SQL*Connect 
to query objects, or direct via SQL queries towards the userobjects.CO_xx_INST tables 
in the Advant OCS relational database. (Oobjects in a Controller are always read through 
AdvaInform SQL*Connect.) 


Each Basic and User Object type has a corresponding userobjects.CO_xx_INST table. “xx” in 
the table name means the object type name. For example, to read an AO object, the query 
format is: 


SELECT value FROM userobjects.co_ao_inst 
WHERE name = ‘ao_five’; 


Reading an object instance from a userobjects.CO_xx_INST table takes approximately the same 
access time as using AdvaInform SQL*Connect. The attributes in the two tables are exactly the 
same. While you can always use the userobjects.CO_xx_INST tables to read the local Basic and 
User Objects, it is often useful to access these objects via AdvaInform SQL*Connect. 
Therefore, it is recommended that you add the Basic Object and User Object types to 
AdvaInform SQL*Connect using the tool described in Chapter 3.5, Using the AdvaInform 
SQL*Connect Client. 
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The reason for the recommendation to read User Object attributes through AdvaInform 
SQL*Connect instead of using SQL towards the User Objects table is that it is not mandatory 
for the User Object to update the database table. By default the database is updated, but it is 
possible to turn off that data shadowing - both through the objects themselves and by using 
Object Handling utilities. 


The only method for reading Basic and User Objects in remote IMS nodes is via AdvaInform 
SQL*Connect. The queries are written against the object type tables. For example, 


SELECT value FROM ao WHERE name = ‘ao_five’; 


3.7.1.3 Queries for Numeric History Data 


Numeric history data is stored in objects called logs. A log stores multiple instances of one 
object attribute value. For instance, $HSFC100,MEASURE-1-o stores multiple instances of the 
measured value for FC100. Each instance is referred to as a log entry, or simply entry. Each 
entry in a log has a value and a corresponding time stamp as shown below: 


Timestamp Value 
25 Jul 95 09:30:00 65.7 
25 Jul 95 09:30:10 66.4 
25 Jul 95 09:30:20 65.9 
25 Jul 95 09:30:30 66.7 
and so on... 


To access data from a numeric log via AdvaInform Reports, you write a query against the 
NUMLOGVAL table which has the attributes shown in Table 3-4. 


Table 3-4. NUMLOGVAL Attributes 


Attribute Data Type Description 
NAME VARCHAR2(41) Log name or Access Name 
TIME DATE Date of the stored value 
MS NUMBER(11) Millisecond time of the stored value 
ENTRYVALUE NUMBER(14,7) The stored value 
ENTRYSTATUS NUMBER(11) The status of the stored value 
OBJECTSTATUS NUMBER(11) The status of the object that provided the 

stored value. 
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When to Use Log Name or Access Name 


There are two ways to specify which log to retrieve data from. The access name is normally the 
name of the data source that you assign to a log when you configure it in the History Builder. 
For instance, TC100, MEASURE (MOD 300) or TC100, VALUE (Master). 


By virtue of the hierarchical log structure of AdvaInform History logs, there can be more than 
one log using the same data source. To distinguish multiple logs with the same data source, 
History automatically assigns a unique default log name to each log. The log name is derived 
from the access name, and has a prefix and suffix appended as shown in Figure 3-22. 


$HSTC100,MEASURE- 1-0 
(eel 


Prefix - $HS indicates History Log _ 4 


Access Name 


Integer to uniquely identify different logs in a 

composite log (for example | = primary,2 = first secondary, 
3 = next secondary, and so on). The number is assigned 
according to the order the log was added to the 

composite log. 


0 = original, r = restored (from archive tape) 


Figure 3-22. Log Name 


You can use the access name to specify which log to retrieve data from when you know the data 
source but do not know the log name. When you use the access name, History uses the seamless 
retrieval criteria, Section 3.7.1.6, Criteria for Seamless Retrieval, to select the most appropriate 
log in the data source’s log hierarchy. Generally, unless other criteria are specified, seamless 
retrieval selects the log that has INSTANTANEOUS or AVERAGE as the calculation algorithm, 
and has a log period that provides the best coverage of the requested time period. 


Some example queries for numeric data are provided below. 
Basic Query for Numeric Data 
This query does not specify a time range or instance. Therefore, it returns all entry values with 


their respective timestamps for TC100,MEASURE. 


Query: 


SELECT to_char(time, ‘mm/dd/yy hh24:mi:ss’), entryvalue 
FROM numlogval 
WHERE name = *TC100,MEASURE’ 
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TIP: 


The time attribute stores the timestamp for an entryvalue. It is a date data type. If you query for 
time directly (without using to_char), you get just the day, month, and year. To get the full 
timestamp including hours, minutes, and seconds, use the to_char function to convert the 
time attribute from the date data type to the character data type. When you convert time to a 
character data type, you must specify the format mask. The example above shows one 
possibility. Some other valid format masks are given below: 


SELECT to_char(time, ‘dd/mm/yy hh24:mi:ss’) 


SELECT to_char(time, ‘dd-mon-yy hh24:mi:ss’ ) 


Other format masks can be used. Note that the symbol for minutes is mi rather than mm. 


Query for Numeric Data from a Secondary Log 


When you query for a secondary log, it is recommended that you use the full log name when 
you know it. This way you are sure to access the intended log. If you use just the access name, 
the seamless retrieval function will select the log based on the seamless retrieval criteria as 
described in Section 3.7.1.6, Criteria for Seamless Retrieval. 


This query is identical to the one before, except that it uses the full log name to specify a 
secondary log. 


Query: 


SELECT to_char(time, ‘mm/dd/yy hh24:mi:ss’), entryvalue 
FROM numlogval 
WHERE name = ‘S$HSTC100,MEASURE-3-o0’ 


Query for a Specific Time Range 


This query is very similar to the basic numeric query. The WHERE clause is expanded with two 
AND phrases that specify the time range as: after 13:34 (1:34 pm) on February 15, 1996, and 
before 13:37 (1:37 pm) on February 15, 1996. 


Query: 


SELECT to_char(time, ‘mm/dd/yy hh24:mi:ss’), entryvalue 
FROM numlogval 

WHERE name = ‘TC100,MEASURE’ 

AND time>=to_date(*02/15/96 13:34:00’, ‘mm/dd/yy hh24:mi:ss’) 
AND time<=to_date(*02/15/96 13:37:00’, ‘mm/dd/yy hh24:mi:ss’) 


TIP: 


The time range is specified as a character data type, and must be converted to a date data type in 
order to be compared to t ime. This conversion is performed by the to_date function. The 
format mask must be specified (see Section 3.7.1.3, Queries for Numeric History Data). 


3BSE 012 638R0001 3-37 


Advalnform® SQL*Connect User’s Guide 
Chapter 3 Using the Advalnform SQL*Connect Client 


3.7.1.4 Query for Data at Intervals 


An interpolation feature of the numlogval view lets you query for data at fixed intervals such as 
every five, ten, or fifteen minutes, even if data is not sampled and stored at such intervals. 


3.7.1.5 Query for a Specific Instance in Time 


Again, this query is very similar to the ones before. In this case, the query will return entry 
values from eight hours ago to the present. 


TIP 


SELECT to_char(time, ‘mm/dd/yy hh24:mi:ss’), entryvalue 
FROM numlogval 

WHERE name = ‘*SHSTC100,MEASURE-1-o0’ 

AND time> (sysdate -8/24) 


The sysdate function provides the system date and time. It is the date datatype. You can 
subtract days or hours from the system time as follows: 


to subtract hours, use the format n/24 and then subtract the fraction from sysdate as in the 
example above. 


to subtract days, subtract an integer value from sysdate. For example: 
AND time > (sysdate - 8) 


This query returns entry values from eight days ago to the present. 


3.7.1.6 Criteria for Seamless Retrieval 


The seamless retrieval function uses the following criteria to search the History database and 
select a log when a request for history data is issued: 


1. 
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Sort logs by percentage of the time period of the request that the log covers, and choose the 
set of logs that are closest in coverage. 


For instance, if the request is for 24 hours, logs may be sorted as follows in descending 
order of preference: 24-hour logs and 168-hour logs, 8-hour logs, and 1-hour logs. Since 
the 24-hour logs and 168-hour logs cover 100% of the requested time period, they would 
be chosen. 


Search the set chosen in step 1, and find all logs that use the specified calculation 
algorithm. Logs that do not use the specified algorithm are dropped from consideration. 


For AdvaInform Reports, the algorithm is always WILDCARD which uses the following 
order of preference: 


a. AVERAGE or INSTANTANEOUS 


These algorithms have equal preference. The first one found in the search is selected, 
and logs with any other calculation are dropped from consideration. 
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MAX/MUM 
MIN/MUM 

SUM 
SUM_OF_SQRS 
STANDARD_DEV 
NUM_OF_VALUES 


At this point the set of logs still under consideration have the same log period (closest to 
percent of coverage of requested time period), and calculation algorithm. 


This set is now searched for the specified retrieval type. One log is selected according to 
retrieval type as follows: 


a. 


If the retrieval type is RAW, one log is selected in the following order of preference: 
1) Pick the log whose storage interval is equal to the time between points in request. 


2) Pick the log whose storage interval is greater than and closest to the time between 
points (so request can be completed in one response). 


3) Pick the log whose storage interval is less than and closest to the time between 
points (more points exist than buffer can hold, MORE_DATA status is returned). 


If the retrieval type is INTERPOLATE, one log is selected in the following order of 
preference: 


1) Pick the log whose storage interval is less than and closest to the time between 
points (so interpolation is more accurate). 


2) Pick the log whose storage interval is equal to the time between points in request. 


3) Pick the log whose storage interval is greater than and closest to the time between 
points. 


3-39 


Advalnform® SQL*Connect User’s Guide 
Chapter 3 Using the Advalnform SQL*Connect Client 


3.7.1.7 Queries for Messages 


Use the EAMSGLOG (Master only) to read historical messages related to IMS Basic (User) 
objects. 


Use the hs_msg view to read historical messages related to CCF and TCL (MOD 300 only). 
These messages include: 


° CCF alarm and parameter change messages 
° TCL Unit and event messages 
° Console log on and alarm acknowledgment messages 


Since there is only one message log that stores CCF and TCL messages, you are not required to 
provide the log name in the query. 


The attributes in hs_msg that are most often used are listed in Table 3-5. 


Table 3-5. hs_msg Attributes 


Attribute Data Type Description 
message char (255) Message text 
locating char (75) Date and time (seconds) of the message. Format: 
yy-mm-dd hh24.mi.ss 
tag_name char (13) Tag name of tag that generated the message 
unit_name char (13) Unit where tag that generated the message resides 
sequence_name char (13) TCL sequence for TCL messages 
message_type number 0 = log on 
1 = alarm 
2 = billboard 
3 = parameter_change 
4 = ladder logic 
5 = SPC 


6 = alarm acknowledgment 
7 = diagnostic 
8 = batch message 


batch_name 


char (40) Associate Batch 300 Batch 


3-40 


3BSE 012 638R0001 


Aavalntorm® SQL*Connect User’s Guide 
Section 4.1 Introduction 


Chapter 4 Using the Advalnform SQL*Connect Server 


4.1 Introduction 
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The AdvaInform SQL*Connect Server provides Advant OCS with cyclic/demand read access 
to data in external databases in the same manner as with process objects. That is, relational 
database data will appear as global objects in Advant OCS. The external databases must 
recognize ANSI SQL though. 


Thus data from the Advant OCS relational database, or a remote database, is accessible from 
any node where SQL queries can be generated such as an OS (Operator Station). The data can 
be used in OS displays in the same manner as if the data was stored in a controller. All you need 
to know is the object name and the object type of the data you want to present. 


SQL* Net provides access to remote oracle databases. 


NOTE 


The SQL Server only supports on demand (one-shot) or cyclic read access. Event 
notification and operations are not supported. 
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4.1.1 Examples of Using the Server 


Figure 4-1 shows how data from a database/tool/application in an external computer, or in the 
Advant OCS relational database, can be presented on an OS (in a display element). The figure 
also shows how the same data can be transferred to an Advant Controller. 


External Computer 


UPDATE VALVE_SP 
SET VALUE=25.7 
WHERE NAME = ‘VSPI1’; 


MY_USER Plant network 


IMS Station 


Advalnform Object Handling 


View @) ® 6) Advalnform Basic Objects ©) 
NAME 
Mie eee SQL Server vSP1 AO 03-OUT.1 
VSP2 Connection _—— TT Cyclicity S4Geer 
Data subscriptions request 
Embedded SQL y VSP2 AO 03-OUT.2 
SQL Server a | a API Cyclicity = 1 min 
Tool application 
Order 


Control network 


Operator Station Controller Order Controller 
Order 
03-OUT.2 03-OUT.1 
Display @ @ 
element —_ 


Figure 4-1. Data from external computer to Controller using a created view in IMS 


The two data transfer methods shown in Figure 4-1 are described below. The numbers at the left 
correspond to the numbers in Figure 4-1. 
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Presentation on an OS 


1 The RDB table in the external computer. The name of the table is “VALVE_SP”. 


2 A user created view. The view is used to map the external VALVE_SP table to the 
Advant OCS object type AO (Analog Output). 


One advantage of mapping to an Advant OCS object type is that a standard Display 
Element can be used for presentation on the Operator Station. 


3,4 Object data is presented in the Operator Station using a standard Display Element for 
AO. The configuration is carried out in exactly the same way as if the object resides in 
a Controller. 
When the Display Element in the OS process display requests for an update, the 
request is received by the AdvaInform SQL*Connect Server. The Server in turn 
fetches new data values from the VALVE_SP table, through the view, and sends data 
back to the OS. 


Transfer to a Controller 


1,2 Same as in table above. 


5, 6 An input connection for the VSP1 object has been set up for the AO Basic Object. 
When the Basic Object requests for data from the VSP1 object (in the VALVE_SP 
table), via AdvaInform SQL*Connect Server and the view, data is fetched from the 
VALVE_SP table and transferred to the output 03-OUT.1 (of type AO). 


7 Data for 03-OUT.1 is received by and stored in the Controller database. 


8 Update of a Controller object (that is an operation) can also be achieved via an 
application program using either the AdvaInform User API services or the SQL 
Procedural Services (see Advalnform SQL*Connect Programmers User’s Guide). 


4.1.2 Object Types vs. Tables and Views 
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The AdvaInform SQL*Connect Server provides Advant OCS objects access to data in external 
Oracle databases. Data can be accessed as if stored as objects in the Advant OCS. 


Before Advant OCS applications can access data in external Oracle tables, object types (as 
listed in the Type Directory) must be mapped to Oracle tables or views. This is done with the 
AdvaInform SQL*Connect Server tool. How to do it is described in the tutorials below. 


The Type Directory is part of the core system while the tables or views are located in the Oracle 
database. Each row in a table or view is mapped as an instance of a specific object type. The 
instance name is the string (text) value in the first column of the row. 


You can connect tables to existing object types and you can create new object types with the 
AdvaInform SQL*Connect Server tool. 


If you create a new object type, you must update the Type Directory and then restart IMS. Thus 
it is to your advantage to use existing object types if that is possible. 
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Another advantage of using an existing object type, such as AI or TEXT (DATA_FCM or 
VA_STRING_FCM for MOD 300), is that the system supports existing object types. For 
instance, the display elements for AI (DATA_FCM for MOD 300) which makes it possible to 
present numerical data in user defined Process Displays. These elements let you define 
numerical fields on Process Displays and use Object Select to open an overlapping Object 
Display. 


Table 4-1 shows how Oracle RDB data are mapped to object data. 


Table 4-1. RDB vs. Object terminology 


Oracle data Object Concepts 
Table or view Object Type 
Row Object Instance 
Column Attribute 


4.1.3 Predefined Tables for Use with the Server 


The following predefined tables in the Advant OCS relational database can be used as data 
sources by the AdvaInform SQL*Connect Server: 


DB_AI 

DB_AO 

DB_DI 

DB_DO 

DB_TEXT 

DB_DAT 

DB_MANSTN 
DB_RATIOSTN 
DB_PIDCON 
DB_DATA_FCM (MOD 300) 
DB_VA_STRING_FCM (MOD 300) 


The tables are useful for two reasons: 
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The Advalnform oracle users can perform SQL updates and inserts to these tables. These 
updates and inserts are allowed with the runtime Oracle license. 


Their structure coincides with the structure of the AdvaInform Basic Objects so the server 
can easily connect them to the corresponding object type. Thus the DB_AI table can be 
connected to the AI Basic Object type, and so on. 
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These features facilitate the following application techniques: 


° An application in a remote database can transfer data into an IMS by applying the SQL 
UPDATE command to the DB_xx tables. This assumes a remote Oracle database and 


proper configuration of SQL*Net and database links to the Advant OCS relational 
database. 


° A DB_xx table can be connected to its corresponding Basic Object type via the 
AdvaInform SQL*Connect Server. In this manner, an application can make information 
available to an Operator Station by updating this DB_xx table. 


° AdvaInform User API and User Objects applications can read data from the tables using 
SQL. 


Figure 4-2 shows an example of using the DB_AI table. 


Application on 
External Node 


2 TCP/IP Network 


=> (Updates and Inserts to the DB_Al Table ) => 


Advant Station 


<——+-| Object Type } 


Object Type Table DB_AI Table 
name value (more columns) 


Al_ONE 15.9 XXX Xx 
Al_TWO 170.4 xxx xx 


Advalnform 
SQL*Connect 
Server 


Al 
<_ 
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Figure 4-2. Using the DB_AI Table with the Server. 


An application program in an external computer can send updates and inserts to the DB_AI 
table via the TCP/IP network (assume SQL*Net and database links). The DB_AT is connected 
by the server to the AI object type. When the application program updates row AI_ONE in the 
table, a similar update is made to the corresponding AI_ONE object instance at its next 
execution. If the application program inserts a new row into the table, a new instance of AI is 
created. The AI instances can be connected via subscriptions to another object. 
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4.1.4 Requirements and Limitations 


When you map an object type to a table or view there are some rules you have to follow: 


The number of columns in the table/view must match the number of attributes of the 
Object Type. For a detailed description of Advant OCS object types, refer to the 
Advalnform Object Types Reference Manual. 


The first column in the table/view must always be a character string since the first attribute 
of an Object Type is the objects name (a character string). 

It is recommended that you enter the name in UPPERCASE letters to avoid problems 
when accessing object instances in run-time. 


The data type of an attribute and that of the corresponding column must match. 
The supported data types are listed in Table 4-2. 


Table 4-2. Mapping of Oracle Data onto Object Data Types 


Oracle Data Type Object Data Type 


VARCHAR(x) string 
NUMBER integer 
NUMBER float 


The length of character strings of the Oracle and Object data types do not have to be equal. 
The character string in the object data type must be equal to, or longer than, the 
corresponding character string in the Oracle table column. 


You must update the server after you add a row to or remove a row from a table or view. 
This operation notifies the AdvaInform SQL*Connect Server that objects have been 
removed from or added to the database. This function is provided on the AdvaInform 
SQL*Connect Server menu. 


The server is also automatically updated on the following occasions: 
— When the IMS is restarted 
— When a request for a deleted object does not succeed 


— On acyclic basis (once every two hours) 


Core System Core System Oracle Oracle 


Display 
element 
C 


soo Gals 


yclical Server Server 7 
presentation Connection Connection Sehihet 
Advant Station 500 OS Advant Station Foreign node 


Figure 4-3. Example of data flow through AdvalInform SQL*Connect-Server 
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4.2 Tutorial 1 - Presenting Advalnform objects on an Operator Station 


Figure 4-4 provides a summary of this first AdvaInform SQL*Connect Server tutorial. 


Data source ject i 
Object instance Operator Station 


Insert/Update DB_AO Display 


SQL*Connect 
Server 


— ie 


a ee | 25.8% 


Figure 4-4. Schematic presentation of Tutorial 1 


You start by entering data into the DB_AO table. Then you connect the DB_AO table to object 
type AO (Analog Output) using the AdvaInform SQL*Connect Server tool. Finally, you access 
the AO data and present it on an Operator Station. 


This is the simplest way to use AdvalInform SQL*Connect Server. It demonstrates all the steps 
required to fetch data from an IMS RDB table for presentation on an Operator Station. 


4.2.1 Preparations 


No specific preparations are needed. 
4.2.2 Step by step description 
1. Choose Database Access from the Station menu to open the Database Access window, 


Figure 4-5. 


Database Access 


SQL*Plus: Release 3.3.2.0.0 - Production on Thu Aug 28 08:11:30 1997 


Copyright (c) Oracle Corporation 1979, 1994. All rights reserved. 


Connected to: 

Oracle? Server Release 7.3.2.3.0 - Production Release 
With the distributed option 

PL/SQL Release 2.3.2.3.0 - Production 


SQL> §j 


Figure 4-5. The Database Access window 
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2. Check that you can access the DB_AO table 


Enter command: 


describe DB_AO; 


The expected result is shown in Figure 4-6. 


SQL> 

SQL> 

SQL> 

SQL> 

SQL> 

SQL> describe db_ao 
Name Nul1? Type 
NAME NOT NULL VARCHAR2( 20) 
DESCRIPTION VARCHAR2( 28) 
STATUS NUMBER(10) 
UNIT VARCHAR2(6) 
RANGE_MIN NUMBER 
RANGE_MAX NUMBER 
VALUE NUMBER 
MAX_LIM NUMBER 
MIN_LIM NUMBER 
START_VALUE NUMBER(5) 
ERROR_TREAT NUMBER(5) 
NO_OF_DEC NUMBER(3) 
SUBSYSTEM NUMBER(3) 
CLASS NUMBER(3) 

SQL> Ef 


Figure 4-6. Describe command on DB_AO 


3. Insert a row into the DB_AO table with the SQL command: 


insert into DB_AO values (‘MYAO’, 
‘My first AO object’, 5, ‘tons’, 
0, 100, 3.14, 100, 0, 10, 2, 2, 3, 3); 


5 is status and means “active”. 
4. Make the insert permanent by entering the command: 
commit; 


You have now inserted character and numeric data into one of the rows of the table 
DB_AO! 


5. Verify that the data you entered at step 3 is in the DB_AO table: 


select * from DB_AO where NAME=’MYAO’; 


Connect table DB_AO to Object Type AO 
6. Open the AdvalInform SQL*Connect Server tool. 


Choose SQL Connect from the AdvaInform menu, and then Server Configuration from 
the sub-menu. This opens the IMS Server Tool window, Figure 4-7. 
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IMS Server Tool 


File Option 


Object Types Connections 


«« Add Connection 


RATIOSTN Remove Connection »» 


Messages 


The Al object type doesn’t have any connections 


Figure 4-7. The IMS Server Tool window 


7. Select AO from the Object Types list. 
8. Enter the name of the data source. 


Enter DB_AO in the field below the <<Add Connection button. Then click on <<Add 
Connection, Figure 4-8. 


File Option Help | 


Object Types Connections 


Al «« Add Connection 
AO 

DAT i 

DI 


Figure 4-8. The IMS Server Tool. Definition of Object Type and Connection. 


Update the Advalnform SQL*Connect Server 
You must always notify the server of new object type definitions. 
9. Choose Save and Update Server from the File menu to update the server 


The configuration is now completed and the AdvaInform SQL*Connect Server will allow 
demand or cyclical data access to your view. 
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Presentation of Advalnform SQL*Connect Server objects 


10. 


11. 


12. 


13. 


14. 


You can use the Object Select function on the OS (Operator Station) to present object data 
in an overlapping object close-up window. 


Update the VALUE attribute in the data source 
In the Database Access window, enter command: 


update DB_AO set VALUE=6.28 where NAME=’MYAO’; 


Store the update in the database 
Enter command commit; 


From the OS Operator Keyboard, select: 


a» Object 
I Req 


Check that the value in the object close-up window changes according to the new object 
value. 


You can also build a display on the OS. 


In that case, use the standard display element AOPDO1 to present the data for object 
MYAO in table DB_AO. 


4.3 Tutorial 2 - Presenting Data from an External RDB on an Operator Station 


Figure 4-9 shows the data flow from the external RDB to the OS screen. 


External RDB IMS Station Operator Station 
Data source: Display 
SETPOINTS SOL*Net SE VIEW Weew) AdvalInform 
*Ne 

SQL*Connect 

NAME =e 
Server 
STATUS <_—_—_| pp 
VALUE 
i es v Controller 


(Basic Object). 4 mer 
Ao. / Application 


Figure 4-9. Mapping of a remote RDB table to an existing object type (AO) 


In this second Sever tutorial, you will map a remote database table to an existing object type. 
Remote means that the RDB table resides in an external node such as a PC. 
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The name of the remote database table is SETPOINTS and it contains external setpoints. The 
values will be used by a Controller application. The structure of the SETPOINTS table is: 


Table column Data type 
NAME VARCHAR(20) 
STATUS NUMBER 
VALUE NUMBER 


You will map the table to the Basic Object type AO. The advantage of mapping towards such an 
object type is that existing display elements on the Operator Station and example programs on 
the IMS can be used. 


Use a database link extrdb to access the SETPOINTS table. The steps for this procedure are 
provided below. 


Enter some data (rows) into the external database. 


4.3.2 Step by step description 
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1. 


Invoke the Database Access window. 


Choose Database Access from the Station menu. In the steps to follow, enter the 
commands in the Database Access window, unless you are instructed to do otherwise. 


Create a database link. 
Enter following command: 


create database link extrdb 
connect to my_user identified by my_passwd 
using ‘service_name’; 


Where: 


- extrdb is the name of the database link which must be the same as the name of hte 
external SID (data base name). 


= service_name is the name of the connection description in the /etc/tnsnames.oa file. 
Check for the existence of the database link. 

Enter command: select * from DBA_DB_LINKS; 

Get a description of the attributes of the AO object type. 


Enter command: describe AO@extrdb 


NOTE 


To be able to map a table/view to an existing object type, the number of columns 
of the table/view must match the number of attributes of the object type. The 
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column data types of the table/view must also match the attribute data types of the 
object type. 


Create a view 


The next step is to create a view, based on the remote SETPOINTS table. A view can be 
regarded as a “window” from which you can read information from a table(s), and write 
information into a table(s). The view can fetch data from different tables. 


In this exercise you will create a view containing the following information from the 
SETPOINTS table: NAME, STATUS, and VALUE. 


5. Create view SP_VIEW. 


Enter the following command (in the Database Access window): 


create view SP_VIEW ( 
dummy3, dummy4, VALUE, 
dummy5, dummy6, dummy7, dummy8, dummy9, dummyl0, dummyl11) 
as 

select NAME, to_char(null), STATUS, to_char(null), 
to_number (null), to_number(null), VALUE, 
to_number (null),to_number (null), to_number(null), 
to_number (null),to_number (null), to_number(null), 
to_number (null) 
from SETPOINTS@extrdb; 


NAME, dummyl, STATUS, dummy2, 


6. Make the view permanent and visible to other users 
Enter command: commit; 
7. Allow gtadmin to read data via your view. 


The server accesses the data sources as Oracle user gtadmin. To grant access to gtadmin, 
enter the following SQL command: 


grant select on SP_VIEW to gtadmin; 
Now gtadmin is granted SELECT access on your view. 
8. Verify that gtadmin can access the view. 
Enter the following commands: 
connect gtadmin (You will need a password to be able to do this) 


select * from MY_USER.SP_VIEW; 


9. Start the AdvaInform SQL Connect Server tool. 


First choose SQL Connect from the AdvaInform menu and then Server Configuration 
from the sub-menu. 


10. Select (highlight) the AO object type. 
11. Enter the name of the view. 


Enter the name of the view you created earlier (my_user.SP_VIEW) into the textbox 
below the <<Add Connection button, then click <<Add Connection. 
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12. Update the server. 
Select Save and Update Server from the File menu. 


13. Use adisplay such as the one from the previous tutorial or an object close-up to present the 
numerical value(s) from the external database table. 


4.4 MS Query Tutorial 


This section contains a tutorial to Request Controller Data by a PC client. 


4.4.1 Start the MS Query 


To start MS Query in your local PC, double click on the Program Manager icon. Then in the 
Program Manager double click on the Microsoft Query icon. 


4.4.2 Receive data to MS Query 


Choose New Query from the File menu. This opens the Select Data Source window. Select a 
data source and click Use. This opens a log in window. Enter your password and click OK. 


If the data source you want to use does not exist in the Data Source window, click on the Other 
button. This displays a list of delivered ODBC Data Sources. Choose a Data Source and click 
OK. The selected Data Source is now displayed in the Select Data Source Window. 


This displays the Add Tables dialog, Figure 4-10. Select the table you want to use in the 
spreadsheet. 


You can limit the scope of tables in the list by specifying the owner. You may also select table 
type or types via the Table Option dialog which is displayed by clicking the Options button. 


= Add Tables 


Figure 4-10. Add Tables Dialog 
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When you select a table, a small window is displayed in the upper part of the Microsoft Query 
window, Figure 4-11. More than one such window displayed at the same time by selecting 
multiple tables. The Add Table dialog does not close until you click on CLOSE. 


Microsoft Query 
File Edit View Format Table Criteria Records Window Help 


(ea [tet] [see] [oA] [Pea] [=[=] [2454] Lt ] fae 


Al 


CLASS 
DESCRIPTION 


[NAME | VALUE | UNIT [DESCRIPTION 


Open a saved query Pe 


Figure 4-11. Microsoft Query window 


These small windows show the available attributes for their respective tables. Verify that the 
automatic query is not active. Select the attribute/attributes that you want to include. They will 
be displayed in a spreadsheet in the lower part of the Microsoft Query window. 


Select Add Criteria from the Criteria menu. This displays an Add Criteria dialog, Figure 4-12. 
Here you can specify the search criteria when executing the query. 


= Add Criteria 
Oo 


[ 


NAME 


equals 


‘AlC71_1] 


Figure 4-12. Add Criteria Dialog 
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To execute the query, choose Query Now from the Records menu, or press the Query Now 
button in the toolbar. The spreadsheet will be filled with data, Figure 4-13. 


Microsoft Query 
File Edit View Format Table Criteria Records Window Help 


fel} [seu] [ae] a'} [Pea] [=] = | [24] 24) LE [ceo] [a2] 


Criteria Field: | NAME 
‘AIC71_1' 


or. 


+ 


VALUE [ UNIT | DESCRIPTION | 
% TEST AIC 71 2 
% TESTAIC?1_1 


Figure 4-13. Completed example 
Before ending the session you have to send a SQL commit command to IMS to release the 
rollback segment in the Oracle database in the IMS. 


Choose View SQL from the View menu. This displays a Statement dialog, Figure 4-14. 


SQL Statement: 
COMMIT 


Figure 4-14. SQL Statement Dialog 


Remove the current SQL Statements, enter: COMMIT and click OK. 
4.5 How to Set Up IMS to Exchange Data with an External Node 


This section describes how to configure SQL*Net for TCP/IP and create database links to 
support the exchange of data between the IMS and external nodes on the Plant Network. 
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4.5.1 SQL*Net TCP/IP 


SQL*Net TCP/IP is the version of SQL*Net used by computers which are connected together 
via a TCP/IP network. SQL*Net is Oracle Corporation’s network interface that allows 
ORACLE tools or applications running on one computer to access, manipulate, and store data in 
ORACLE databases residing on other computers. 


SQL*Net is an elaboration of the two task (client/host processes) architecture in which the client 
(user) task runs as a separate operating system process from the host task of the ORACLE 
kernel. Instead of communication between processes on one machine, the communication takes 
place over the network. 


If your applications require SQL communication over the TCP/IP network, you have to 
configure SQL*Net TCP/IP in the external computer. 


4.5.2 Database Links 


After configuring SQL*Net, you have to link the databases between the IMS and the external 
node. Depending on the direction of access, database links must be created in the external node 
and/or in the IMS. Configuration of database links must always come after verification of 
SQL*Net between the IMS relational database and the external node. 


Databases in the IMS and the external node must be linked. Depending on the direction of 
access, database links must be created in the external node and/or in the IMS. Configuration 
of database links must always come after verification of SQL*Net between the IMS relational 
database and the external node. Figure 4-15 shows three possibilities. 


Oracle RDBMS 


Plant Network 


Control Network 


Controller 


Ik DCS Database 


Figure 4-15. Database links to an Oracle database in an external node. 
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° Path 1 shows a database link from Oracle database in external node to the AdvaInform 
relational database. 


A database link must be created in the external node. The link must log in as a valid Oracle 
user. See the Advant Station 500 Series IMS User’s Guide for information on how to 
define new users including database users. 


The illustration shows a complete Oracle RDBMS in the external node. However, it is 
possible to gain access to the AdvaInforms relational database from analysis packages 
such as spreadsheets which have an SQL driver. No database link has to be created in this 
case. However, SQL*Net must be installed in the external node. 


° Path 2 shows a database link from the AdvaInform relational database to remote relational 
databases in external nodes. 


A database link is created to the database instance in the external node. It is recommended 
that a specific user be defined in the external database to manage access from the 
Advalnform Basic Functions relational database. 


° Path 3 shows the AdvaInform SQL*Connect Client which makes it possible for the 
AdvalInform Basic Functions relational database to access information stored in the 
Advant OCS process database as if it were stored in relational database tables. Once a link 
has been created from the Oracle database in the external node to the AdvaInform Basic 
Functions relational database, it is possible to access process data over the Plant Network. 
Access can be routed through any Advant Oracle user with ENGINEER privileges. 


How to Configure Database Links from External Nodes to the IMS 


Preferably, database links from external nodes are created by the database administrators for 
those external nodes. Refer to the documentation on the software licenses for the external nodes 
for configuration of TCP/IP, SQL*Net and Oracle RDBMS. 


One example of a configuration procedure is as follows: 
1. Configure and verify the TCP/IP communication. 


The TCP/IP address of the IMS node can be checked by entering the HP-UX command: 
/usr/sbin/ifconfig lan 


2. Configure and verify SQL*Net. 


The name of the AdvaInform relational database instance can be checked by entering the 
HP-UX command: echo $ORACLE_SID 


3. Configure and verify the database link. 


How to Configure Database Links from Advalnform nodes to External Nodes 


Database links are created by an IMS user with appropriate privileges in the IMS relational 
database. The IMS user must at least be of the category ENGINEER. 


One example of a configuration procedure is as follows: Configure and verify TCP/IP 
communication, SQL*Net, and the database link. 


The tables that allow IMS tools access must be granted access by the database administrator in 
the external node. It is recommended that a separate user be defined for access by the IMS. 
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The following is an example of how to create a database link: 


Assume that you want to create a database link to an Oracle instance called REMOTEDB. Also 
assume that the Oracle user name is “USERIMSACCESS” and the password “IMSPASSW”. 


To create the required link choose Database Access from the Station menu, and then enter: 


CREATE DATABASE LINK REMOTEDB CONNECT TO USERIMSACCESS 
IDENTIFIED BY IMSPASSW USING ‘service_name’ ; 


“service_name’ is the name of the connection description to the external database accessible 
through SQL*Net. 


The above entry establishes a database link in the IMS relational database for the specified user. 
All tools and applications in the IMS are able to access tables in the external node through the 
user “USERIMSACCESS”. 


Assume further that the database link above has been created and that you want to access the 
column value in the table “CALCVAL” to which “USERIMSACCESS” has been granted 
access. Then choose Database Access from the Station menu and enter: 


SELECT VALUE FROM CALCVAL@REMOTEDB ; 


4.6 The Advalnform SQL*Connect Server Tool 
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This section describes the AdvaInform SQL*Connect Server Tool and its menus, Figure 4-16. 
How to use the tool is described in the tutorials. 
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Revert 

Save Changes 

Save and Update Server Create object type... 

Update Server Remove object type... 

Exit Install/deinstall existing object type... 


Opfion 


Object Types Connections 


«« Add Connection 


Remove Connection »> 


Messages 


The Al object type doesn’t have any connections 


Figure 4-16. The Advalnform SQL*Connect Server Tool window 


There are three major procedures for the AdvaInform SQL*Connect Server Tool: 


° Connect predefined database tables in AdvaInform Basic Functions to object types, for 
example DB_ATI 


° Connect database views to object types 


° Install or deinstall object types from the type directory. 
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Lists 


Object Types 


Connections 


Messages 


Buttons and Text fields 


<< Add Connection 


Remove Connection >> 


The File menu 


Revert 


Save Changes 


Save and Update Server 
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The (scrollable) Object Types list shows all object types you can 
connect to Oracle database tables. The list shows all predefined 
object types and also the object types that have been created with 
the AdvaInform SQL*Connect Server Tool. 


When you select an object type in the list all defined database 
connections for the object type are shown in the (scrollable) 
Connections list. 


Presents information and error messages depending on what 
operation has been performed. For example, if you select an 
object type with no connection defined, this can be read in the 
Messages window. 


To add a new connection: Type in the name of table/view in the 
text field below the button and then press the << Add Connection 
button. 


To remove a connection: Select a connection in the Connection 
list and then press the Remove Connection >> button. 


The actual installation of an object type into the AdvaInform 
SQL*Connect Server is not done until you choose Save Changes 
from the File menu. By choosing Revert you can revert changes 
made after the last save. This includes Remove Connection but 
not creation of a new object type or removal of a created object 


type. 

Stores configuration data permanently. 

The configuration data you have entered can not be used by the 
core system until the server has been updated. When you choose 
Save and Update Server the configuration data is stored and the 
AdvaInform SQL*Connect Server task is told to fetch the new 


configuration data and use it to test if objects should be created or 
removed. 


The AdvaInform SQL*Connect Server task is also updated when: 
° Advant Station is started, or 


° An access is made towards an object where the 
corresponding row has been removed since the last time the 
server was updated. 


Insertion of new rows are not detected automatically. 
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Update Server The Update Server menu item does not store any configuration, 
but rather updates the server. This is useful if you have changed 
the contents of a table by deleting or inserting rows, and you want 
the changes to become active. 


Exit Exit the AdvaInform SQL*Connect Server Tool. 


The Option menu 


Create object type... Displays a dialog for entering the name of the Oracle table/view 
specifying the new object type, Figure 4-17. 
The result will be an object type description in the form of an 
OTDL (Object Type Description Language) file. The generation 
of a new Type Directory is done automatically, but for the 
changes to take effect, IMS must be restarted. 


To make the new object type known to other nodes, the Core 
System’s Type Directory must be copied to those nodes. The 
name entered in the Object Type Name field is the name for the 
object type when it is added to the Core System’s Type Directory. 


Section 4.7, How to Update the Object Type Directory provides 
more information on how to update the Type Directory. 


Oracle Table/View Name 


| MYTYPEVIEW | 


Object Type Name 


| MYTYPE | 


Figure 4-17. Create Object Type Dialog Box 
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Remove object type... Displays a dialog box to remove an object type, Figure 4-18. The 
dialog box contains a list of all user-created object types. 


To remove an object type select it and click on OK. The object 
type is removed from the Core System’s off-line Type Directory. 
The operation also removes the connection between the database 
and the server. This operation takes effect immediately and can 
not be undone. 


Remove Object Type 


Object Types Created By User 
MYTYPE 


Coc] Ler] (ie J] 


Figure 4-18. Remove Object Type Dialog Box 
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Displays a dialog box to install and/or deinstall object types in the 
Type Directory, Figure 4-19. 


The Type Directory contains many object types that are not 
supported by the AdvaInform SQL*Connect Server (as the pre- 
installed types such as AI and AO are). The un-supported object 
types can be installed in the AdvaInform SQL*Connect Server 
via the Install/deinstall existing object type... dialog in the 
AdvaInform SQL*Connect Server Tool. 


The dialog has two lists with object type names. The Deinstalled 
Types list contains all types in the type directory that are not 
available from the AdvaInform SQL*Connect Server. The 
Installed Types list contains all types that are installed. Object 
types can be moved between the two lists by selecting the type 
name in a list and then clicking on the << Install or Deinstall >> 
buttons. 


When an object type is installed, it’s name is included in the 
Object Types list in the AdvaInform SQL*Connect Server Tool 
window. You can then add connections to the object type. 


To deinstall an object type, you remove it from the list of object 
types accepting connections. All connections to an object type 
must be removed before you deinstall the object type. Predefined 
object types, like AI, AO etc., can not be removed. 


You can install all types in the type directory via the tool. 
However, some object types contain attributes not supported by 
the AdvaInform SQL*Connect Server. These attributes are struct, 
union and open array. Check the Type Directory include file 
stored in directory /opt /advant/TypeDir/include/ 
omf_<object_type>.-h for these attributes before you start 
adding a new type. 


Install/deinstall Object Type 


Deinstalled Types 


ACNODE 
AEHAWKRIDGEINTERFACE 


ARCHDEV 
pee 
rs ASNODE 
[Deinstatl >>] BASICOBJECT 


BHG 
BHM 


BHO 
BLO 
BLT 


Lox | 


ai 


Figure 4-19. Install/deinstall Object Type Dialog Box 
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4.7 How to Update the Object Type Directory 
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The Object Type Directory is a place holder for information on all object types known by the 
Advant OCS. When you define new object types via either the AdvaBuild Object Type Builder 
or the AdvaInform SQL*Connect Server, you must update the applicable object type directories 
in order to make the new object types known and accessible. 


This procedure requires access at the ocsmgr user level and superuser (root) password. 
After you add a new object type via the AdvaInform SQL*Connect Server, update the Object 
Type Directory as follows: 


1s 
2. 


Choose IMS Terminal Window from the Station menu to open a terminal window. 
Become the ocsmgr _ user. Enter command: 
S$ su - ocsmgr 


“99 


The first argument “-”, means that the environment will be changed to what would be 
expected if you logged in as the specified user (ocsmgr). 


Source the IMS environment file. Note the space after the dot (“.”’)! 
S$ . /opt/advant/IMS/etc/IMSenvironment 
Change working directory to TypeDir/bin 
S$ cd /opt/advant/TypeDir/bin 
Execute the tdgen script: 
S$ ./tdgen typedir/password 
where the passwrod = typedir default 


This takes approximately one hour. The script creates a new shared library that becomes 
the new Object Type Directory. 


Log in as root user and stop IMS. Enter the following commands: 


$ su 

Password: root password 

# /opt/advant/Startup/bin/IMSstop 
# exit 


Save the old shared library. Then rename the new shared library to the name of the shared 
library being used. 


$ ‘ed .2/1ib 
$ mv libtdTypeDirData.sl libtdTypeDirData.sl.old 
S$ mv libtdTypeDirData.sl.new libtdTypeDirData.sl 


Log in as root and restart IMS: 


$ su 

Password:<root password> 

# /opt/advant/Startup/bin/IMSstart 
# exit 


When you are confident that the new Type Directory works properly, delete the old one. 
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5.1 Preventive Maintenance 


5.1.1 General 


Refer to the Advant Station 500 Series IMS User’s Guide for maintenance information. 


5.1.2 The Location table 


You should make it a habit to run the gtuCheckLT utility at regular intervals to make sure that 
the location table is up to date. 


5.2 Error Messages 


5.2.1 The Advalnform SQL*Connect Client 


5.2.1.1 Fatal errors 
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The messages from the AdvalInform SQL*Connect Client are written to log files stored in 
directory /var/opt/advant/log. In messages below, % indicates a name (text) or a 
numeric value. Whether it is a name or a value can be determined from the proceeding word, for 
example “Record” in the third message below. The first figure in the error messages described 
below corresponds to the message types. Example: Messages in the interval 600 to 639 concerns 
format errors. 


00700,0, “Out of memory while performing essential allocations.” 
Cause: The user resource limits have been exceeded. 


Action: Increase user the resource limits. 


00702,0, “Internal error - call customer support.” 


Cause: An internal error has occurred. 
Action: Note how the error was produced and contact your customer support 
representative. 
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5.2.1.2 Format errors 


00610,0, “Warning: Format error in Record %ld: - on table %s.” 


Cause: The record is corrupted or datatype conversion has failed. 
Action: Verify that the record is not corrupted or choose a different datatype 
conversion. 


00630,0, “Record %d Table %s Column %s: field has format error.” 


Cause: A corrupt record has been found or conversion could not be completed due toa 
format error. 


Action: Ensure that the data is not corrupted and that the format is correct. 


5.2.2 The Advalnform SQL*Connect Server 


Most of the message texts described below includes a parameter - P1, P2 and so on. The 
meaning of each of these parameters is described below each message text. 


5.2.2.1 Fatal errors 


ORACLE error, (errno = <P1>) 
Parameters: P1: ORACLE error number 


Audience: Engineer 
Cause: An error occurred during a Oracle access. 
Action: Check the meaning of this error number with the oerr command. 


Failed to create exit handler, (errno = <P1>) 
Parameters: P1: Operating system error 
Audience: Engineer 


Cause: The AdvaInform SQL*Connect Server failed to define a exit handler during 
the start-up phase. Operating system related error. 


Action: Check meaning of this error number for your operating system or contact 
ABB. 
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Failed to login to ORACLE, (errno = <P1>) 
Parameters: P1: ORACLE error number 
Audience: Engineer 


Cause: The Advalnform SQL*Connect Server failed to login to ORACLE during the 
start-up phase. 


Action: Check the meaning of this error number with the oerr command. 


Failed to connect to OMF, (errno = <P1>) 
Parameters: P1: OMF return status 
Audience: Engineer 


Cause: An error occurred in the start-up phase of the AdvaInform SQL*Connect 
Server. The connection to OMF didn’t succeed. 


Action: Check for error logs from OMF and if the omfPM process is running. If not 
running, restart Advant Station. 


Failed to initiate IPC, (errno = <P1>) 


Parameters: P1: Operating system error number 
Audience: Engineer 
Cause: The AdvaInform SQL*Connect Server failed to create devices for 


interprocess communication. Operating system specific error. 


Action: Check the meaning of this error number for your operating system or contact 
ABB. 


Failed to create objects, (errno = <P1>) 


Parameters: P1: OMF return status 


Audience: Engineer 
Cause: The creation of objects failed. 
Action: Contact ABB. 


Failed to delete object, (errno = <P1>) 


Parameters: P1: OMF return status 


Audience: Engineer 
Cause: Failed to delete object or group. OMF error. 
Action: Contact ABB. 
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Failed to activate objects, (errno = <P1>) 


Parameters: P1: OMF return status 


Audience: Engineer 
Cause: Failed to activate objects. OMF error. 
Action: Contact ABB. 


5.2.2.2 Non fatal errors 


System error, (errno = <P1>) 


Parameters: P1: Operating system error number 


Audience: Engineer 

Cause: Operating system related error. 

Action: Check the meaning of this error number for your operating system or contact 
ABB. 


OMF error, (errno = <P1>) 


Parameters: P1: OMF return status 


Audience: Engineer 
Cause: An error occurred during a OME access. 
Action: Contact ABB. 


ORACLE error, (errno = <P1>) 
Parameters: P1: ORACLE error number 


Audience: Engineer 
Cause: An error occurred during a Oracle access. 
Action: Check the meaning of this error number with the oerr command. 


OMF error during Server access, (errno = <P1>) 
Parameters: Pl: OMF return status 
Audience: Engineer 


Cause: An OME error occurred when the AdvaInform SQL*Connect Server was 
accessed from a client. 


Action: Check for error logs from OMF and if the omfPM process is running. If not 
running, restart Advant Station. 
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Object type <P1> not found in type directory, (errno = <P2>) 


Parameters: P1: Object type name 
P2: OMF return status 


Audience: Engineer 


Cause: The AdvaInform SQL*Connect Server tried to find a object type not present 
in the type directory. 


Action: Is the used type directory the correct one? Should this object type be present 
in the type directory? 


Attribute <P1> for object type <P2> is incorrect, (errno = <P1>) 


Parameters: P1: Attribute number 
P2: Object type 
P3: OMF return status 


Audience: Engineer 


Cause: An OMEF error occurred when the AdvaInform SQL*Connect Server was 
accessed from a client. The subscribed attribute didn’t exist in the type 
directory. There is an inconsistency between the type directory in the client 
and the one used by AdvaInform SQL*Connect. 


Action: Determine that type directories used by clients to the AdvaInform 
SQL*Connect Server are consistent with the one that is used by AdvaInform 
SQL*Connect. 


Failed to create objects, (errno = <P1>) 


Parameters: P1: OMF return status 


Audience: Engineer 
Cause: The creation of objects failed. 
Action: Contact ABB. 


Failed to delete object, (errno = <P1>) 

Parameters: Pl: OMF return status 

Audience: Engineer 

Cause: Failed to delete object or group. OMF error. 
Action: Contact ABB. 
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Failed to store context, (errno = <P1>) 
Parameters: Pl: OMF return status 
Audience: Engineer 


Cause: The AdvaInform SQL*Connect Server was not able to store object identities 
in a file. This information is used when the Server is restarted to recreate 
objects with the previously used object identity. The objects will now be given 
new identities. 


Action: Check if the disks are full. 


Failed to restore context, (errno = <P1>) 
Parameters: P1: OMF return status 
Audience: Engineer 


Cause: The AdvalInform SQL*Connect Server was not able to restore object identities 
from a file. The objects will be given new object identities. 


Action: No action. 


Failed to delete <P1> object, (errno = <P2>) 


Parameters: P1: Object name 
P2: OMF return status 


Audience: Engineer 
Cause: Failed to delete a object. OMF error. 
Action: Contact ABB. 


Failed to create <P1> object, (errno = <P2>) 


Parameters: P1: Object name 
P2: OMF return status 


Audience: Engineer 

Cause: Not able to create a new object or extend the existing group with the object. 
OMF error. 

Action: Contact ABB. 


Failed to bind <P1> object, (errno = <P2>) 


Parameters: P1: Object name 
P2: OMF return status 


Audience: Engineer 
Cause: Not able to connect a new object to it’s implementation. OMF error. 


Action: Contact ABB. 
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5.2.3 Oracle oerr on-line tool 


3BSE 012 638R0001 


Error messages related to Oracle tools can be investigated further by using the oerr on-line tool 
from an IMS terminal window. This applies to all of the error messages issued by any of the 
installed Oracle tools. These types of messages are presented in two ways: 


° In interactive mode (for example when using the Object Presentations) the message 
(starting with the ORA number) is displayed at the bottom line of the window 


° In a trace file. This occurs when a failure in hardware or software (system or an Oracle 
tool) prevents an instance from continuing work. 


The trace files reside in the directory /var/opt/advant/log/oracle. The files are in 
ascii format. To find the trace file of interest for your problem, check the date of the files. Type 
the file to get the error number and use cerr to get a description. 


Example: 


To get a better description of the Oracle message ORA-6100 than what is supplied by the 
message itself: 


1. Open a terminal window. 
2. Entercommand: oerr ora 6100 


This provides the cause of the error as well as a suggestion on what action you should take to fix 
the problem. 
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Chapter 6 FAQ’s and Recommendations 


6.1 FAQ - Frequently Asked Questions 


FAQ’s are questions often put to ABB Industrial Systems support centers. For each new 
release/revision of this guide the list will be updated. 


These are the most common questions received so far: 


Why are the following error messages displayed when I try to SELECT from the 
AdvaInform SQL*Connect tables (AI, AO, ...etc)? 


“ORA-01031: insufficient privileges” 
and 
“ORA-02063: preceding line from GTW” 


The object names in the Location Table are used when you try to execute your select 
statements. The above error messages are displayed if the total number of objects exceeds 
the upper limit set for that type (default setting is 50), and you are not using “WHERE 
NAME ="xxx”. 


This limit is used to prevent a heavy impact on the system load. If you want to change the 
limit - increase or decrease - refer to Section 3.5, The Client Object Type Configuration 
Tool. 


How do I handle wild card queries? For instance with condition “WHERE NAME LIKE 
“ABC%’. 


AdvaInform SQL*Connect reads data from all objects in the Location Table for the 
requested type and then filters the data. This makes the SELECT very slow. Avoid LIKE 


o_o 


and sub-selects. Use “=“ or “IN” instead 


How can I use AdvalInform SQL*Connect to read process data from my PC application 
(such as Excel)? 


You can get process data to your PC application via SQL SELECT statements towards AI, 
AO and other such tables in an IMS. 


Example: SELECT VALUE FROM AI WHERE NAME = ‘pres.1.2’; 


This statement sends a symbol name translation, and afterwards a demand subscription to 
the Advant Controller. 


For an example on how to do this, refer to Section 3.3, Tutorial 2 - How to Read Data from 
an Advant OCS Object into an External PC. 
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Is it possible to directly access Advant Controller TTD logs in a Master Network? 


Yes, but TTD log variables have to be mapped as described in the Advalnform Basic 
Function User’s Guide. After that you can access TTD logs either by SQL or User API 
calls. Use for example the following SQL query: 


SELECT*FROM NUMLOGVAL WHERE NAME = “TTD_XX_XX_XX_XX”. 


The “TTD_” name must be TTD configured. This means it must exist in the TTDMAP 
table. This will cause more CPU load in the Process Station compared to access towards 
History. 


You can also use User API for the same purpose. Refer to the Advalnform User API User's 
Guide for more information. 


How, why and when should a user reference the Location Table? Can the Location Table 
be used to any advantage in an application? For example, should a query be performed 
towards the Location Table to retrieve data to be used as a pick list for an application? 


The Location Table shall Not be used by any application! ABB does not guarantee any 
compatibility or even that it will exist in future versions of AdvaInform SQL*Connect. 


Do I have to map the TTD logs in order to log data in History? 


No. You only need to map TTD logs if you are going to request them via SQL or through 
the AdvaInform User API. 


In what order shall I remove a TTD log and the mapping when a TTD log is deleted or 
moved? 


First remove the TTD mapping (do an unmap) and then delete the TTD log. 
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